Deals

Deals represent an underwriting application for a merchant seeking an MCA (Merchant Cash Advance). Each deal can have one or more bank statements and documents attached for analysis. Once processing is complete, the deal report includes financials, transaction screening results, a composite health score, and an underwriting recommendation.

Deal status progresses through new → processing → under_review → ready. A deal reaches ready when all attached documents have been processed and the underwriting report is available.

Retrieve a paginated list of deals for your organization. Supports free-text search, status filtering, and column sorting.

Query Parameters

Name	Type	Required	Description
page	integer	Default: 1	Page number (1-indexed)
per_page	integer	Default: 25	Results per page (max 100)
q	string	Optional	Full-text search across business name, DBA name, and owner name
status	string	Optional	Filter by deal status: new, processing, under_review, ready
sort	string	Default: updated_at	Sort field: created_at, updated_at, business_name, status, health_score
order	string	Default: desc	Sort direction: asc or desc

Example

curl

curl -X GET "https://api.banklyze.com/v1/deals?status=ready&page=1&per_page=10" \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "data": [
    {
      "id": 1,
      "business_name": "Acme Trucking LLC",
      "dba_name": "Acme Freight",
      "owner_name": "John Smith",
      "industry": "Transportation",
      "entity_type": "llc",
      "source_type": "broker",
      "status": "ready",
      "document_count": 3,
      "health_score": 72.5,
      "health_grade": "B",
      "avg_monthly_deposits": 125430.00,
      "avg_daily_balance": 34500.00,
      "funding_amount_requested": 50000.00,
      "screening_flags": 2,
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-15T10:35:00Z"
    },
    {
      "id": 2,
      "business_name": "Blue Sky Catering Inc",
      "dba_name": null,
      "owner_name": "Maria Gonzalez",
      "industry": "Food & Beverage",
      "entity_type": "corp",
      "source_type": "direct",
      "status": "ready",
      "document_count": 2,
      "health_score": 81.3,
      "health_grade": "A",
      "avg_monthly_deposits": 88200.00,
      "avg_daily_balance": 22100.00,
      "funding_amount_requested": 35000.00,
      "screening_flags": 0,
      "created_at": "2026-01-20T08:15:00Z",
      "updated_at": "2026-01-20T08:42:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 10,
    "total": 142,
    "total_pages": 15
  }
}

Retrieve aggregated deal statistics for your organization. Use this endpoint to power dashboard KPI cards showing deal pipeline health, approval rates, and volume metrics.

Example

curl

curl -X GET https://api.banklyze.com/v1/deals/stats \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "total_deals": 142,
  "deals_by_status": {
    "new": 18,
    "processing": 4,
    "under_review": 31,
    "ready": 89
  },
  "avg_health_score": 68.4,
  "avg_funding_requested": 47250.00,
  "total_approved": 63,
  "total_declined": 24,
  "total_funded": 39,
  "deals_this_week": 12,
  "deals_this_month": 47
}

Create a new underwriting deal. Returns a DealSummaryResponse. After creation, upload bank statements via POST /deals/{deal_id}/documents to begin the analysis pipeline.

Request Body

Name	Type	Required	Description
business_name	string	Required	Legal business name (max 500 characters)
funding_amount_requested	number	Required	Requested funding amount in USD (must be greater than 0)
dba_name	string	Optional	Doing-business-as name (max 500 characters)
owner_name	string	Optional	Business owner full name
ein	string	Optional	9-digit Employer Identification Number (digits only, no dashes)
entity_type	string	Optional	Business entity type: llc, corp, sole_proprietor, partnership, non_profit
industry	string	Optional	Business industry or vertical
source_type	string	Optional	Lead source: direct, broker, referral, crm, api

Example

curl

curl -X POST https://api.banklyze.com/v1/deals \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Acme Trucking LLC",
    "funding_amount_requested": 50000,
    "dba_name": "Acme Freight",
    "owner_name": "John Smith",
    "ein": "123456789",
    "entity_type": "llc",
    "industry": "Transportation",
    "source_type": "broker"
  }'

Response

Response — 201 Created

{
  "id": 42,
  "business_name": "Acme Trucking LLC",
  "dba_name": "Acme Freight",
  "owner_name": "John Smith",
  "industry": "Transportation",
  "entity_type": "llc",
  "source_type": "broker",
  "status": "new",
  "document_count": 0,
  "health_score": null,
  "health_grade": null,
  "avg_monthly_deposits": null,
  "avg_daily_balance": null,
  "funding_amount_requested": 50000.00,
  "screening_flags": 0,
  "created_at": "2026-02-15T14:00:00Z",
  "updated_at": "2026-02-15T14:00:00Z"
}

Retrieve a single deal by ID with the complete underwriting report. The response includes business information, financial metrics, transaction screening results, composite health score, and the underwriting recommendation. The deal must have a status of ready for the full report fields to be populated.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Example

curl

curl -X GET https://api.banklyze.com/v1/deals/42 \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "report_date": "2026-02-15",
  "business": {
    "id": 42,
    "business_name": "Acme Trucking LLC",
    "dba_name": "Acme Freight",
    "owner_name": "John Smith",
    "status": "ready",
    "entity_type": "llc",
    "ein": "123456789",
    "industry": "Transportation",
    "source_type": "broker"
  },
  "funding_amount_requested": 50000.00,
  "ai_summary": "Acme Trucking shows consistent deposit volumes averaging $125K/month over the review period. Revenue trend is stable with moderate seasonality. NSF count is within acceptable thresholds at 2 incidents. Overall profile supports a conditional approval at a reduced advance amount.",
  "coverage": {
    "months_covered": 3,
    "days_covered": 90,
    "statement_count": 3
  },
  "financials": {
    "avg_monthly_deposits": 125430.00,
    "avg_daily_balance": 34500.00,
    "ending_balance": 41200.00,
    "total_deposits": 376290.00,
    "total_withdrawals": 334210.00,
    "deposit_frequency_per_month": 18.3
  },
  "nsf_overdraft": {
    "total_nsf_fees": 2,
    "total_overdraft_fees": 0,
    "nsf_months": 1
  },
  "screening": {
    "total_flags": 2,
    "buckets": {
      "large_unusual_deposit": 1,
      "repeat_charge": 1
    }
  },
  "health": {
    "score": 72.5,
    "grade": "B",
    "factors": {
      "revenue": 78.0,
      "balance_health": 70.0,
      "nsf_overdraft": 85.0,
      "deposit_frequency": 74.0,
      "revenue_trend": 68.0,
      "debt_service": 66.0
    }
  },
  "recommendation": {
    "decision": "approve",
    "total_score": 86.7,
    "max_advance": 37629.00,
    "cfcr": 1.45,
    "ruleset_name": "Default MCA"
  }
}

Partially update a deal. Only the fields provided in the request body are updated. All fields from the create endpoint are patchable.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Example

curl

curl -X PATCH https://api.banklyze.com/v1/deals/42 \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "funding_amount_requested": 75000,
    "owner_name": "Jonathan Smith",
    "industry": "Logistics"
  }'

Permanently delete a deal and all associated documents, transactions, analysis results, notes, and recommendation data. This action is irreversible.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Example

curl

curl -X DELETE https://api.banklyze.com/v1/deals/42 \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "status": "ok",
  "message": "Deal deleted successfully"
}

Record a final underwriting decision on a deal. Once set, the decision is recorded in the deal audit trail. A deal can be re-decisioned if circumstances change.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Request Body

Name	Type	Required	Description
decision	string	Required	The underwriting decision: approve, decline, or funded

Example

curl

curl -X POST https://api.banklyze.com/v1/deals/42/decision \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"decision": "approve"}'

Retrieve the computed underwriting recommendation for a deal, including factor-level scores, weighted contributions, maximum advance calculation, and CFCR. Results are cached for 30 seconds. The deal must be in ready status.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Example

curl

curl -X GET https://api.banklyze.com/v1/deals/42/recommendation \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "deal_id": 42,
  "ruleset_id": 1,
  "ruleset_name": "Default MCA",
  "total_score": 86.7,
  "decision": "approve",
  "max_advance": 37629.00,
  "cfcr": 1.45,
  "factor_scores": {
    "revenue": { "score": 78.0, "weight": 15, "weighted": 11.7 },
    "balance_health": { "score": 70.0, "weight": 15, "weighted": 10.5 },
    "nsf_overdraft": { "score": 85.0, "weight": 15, "weighted": 12.75 },
    "deposit_frequency": { "score": 74.0, "weight": 10, "weighted": 7.4 },
    "revenue_trend": { "score": 68.0, "weight": 10, "weighted": 6.8 },
    "debt_service": { "score": 66.0, "weight": 10, "weighted": 6.6 },
    "transaction_screening": { "score": 80.0, "weight": 10, "weighted": 8.0 },
    "health_score": { "score": 72.5, "weight": 10, "weighted": 7.25 },
    "cross_doc": { "score": 95.0, "weight": 5, "weighted": 4.75 }
  },
  "generated_at": "2026-02-15T14:30:00Z",
  "cached": false
}

Evaluate a deal against one or more custom rulesets simultaneously. Returns a side-by-side comparison of scores and decisions across all specified rulesets. Useful for scenario analysis or when your organization uses different underwriting criteria for different product types.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Query Parameters

Name	Type	Required	Description
ruleset_id	integer	Optional	A single ruleset ID to evaluate against
ruleset_ids	integer[]	Optional	Multiple ruleset IDs — repeat the parameter for each ID (e.g. ?ruleset_ids=1&ruleset_ids=2)

Example

curl

curl -X POST "https://api.banklyze.com/v1/deals/42/evaluate?ruleset_ids=1&ruleset_ids=2" \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "deal_id": 42,
  "evaluations": [
    {
      "ruleset_id": 1,
      "ruleset_name": "Default MCA",
      "total_score": 86.7,
      "decision": "approve",
      "max_advance": 37629.00,
      "cfcr": 1.45
    },
    {
      "ruleset_id": 2,
      "ruleset_name": "Conservative",
      "total_score": 74.2,
      "decision": "decline",
      "max_advance": null,
      "cfcr": 1.45
    }
  ]
}

Re-run the AI narrative summary generation for a deal using the current transaction data and analysis results. The new summary is generated asynchronously using Claude and will update the deal report once complete. Useful after correcting transactions or uploading additional documents.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Example

curl

curl -X POST https://api.banklyze.com/v1/deals/42/regenerate-summary \
  -H "X-API-Key: your_api_key_here"

Response

Response — 202 Accepted

{
  "status": "ok",
  "message": "AI summary regeneration queued",
  "deal_id": 42
}

Create multiple deals in a single request. Accepts an array of deal objects using the same fields as the single create endpoint. Maximum of 50 deals per request. Partial failures are reported in the errors array — deals that fail validation are skipped while valid ones are still created.

Request Body

Name	Type	Required	Description
(array)	DealCreateRequest[]	Required	Array of deal objects. Each object accepts the same fields as POST /deals. Maximum 50 items.

Example

curl

curl -X POST https://api.banklyze.com/v1/deals/batch \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "business_name": "Acme Trucking LLC",
      "funding_amount_requested": 50000,
      "entity_type": "llc",
      "owner_name": "John Smith"
    },
    {
      "business_name": "Blue Sky Catering Inc",
      "funding_amount_requested": 35000,
      "entity_type": "corp",
      "owner_name": "Maria Gonzalez"
    }
  ]'

Response

Response — 200 OK

{
  "created": [
    {
      "id": 43,
      "business_name": "Acme Trucking LLC",
      "status": "new",
      "funding_amount_requested": 50000.00,
      "created_at": "2026-02-15T14:00:00Z"
    },
    {
      "id": 44,
      "business_name": "Blue Sky Catering Inc",
      "status": "new",
      "funding_amount_requested": 35000.00,
      "created_at": "2026-02-15T14:00:00Z"
    }
  ],
  "errors": [],
  "total_created": 2,
  "total_errors": 0
}

Retrieve a paginated list of all transactions across all documents attached to a deal. This is a convenience endpoint that aggregates transactions from every processed document in the deal. Individual document transactions are also available via GET /documents/{document_id}/transactions.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Query Parameters

Name	Type	Required	Description
page	integer	Default: 1	Page number
per_page	integer	Default: 50	Results per page (max 200)
flagged	boolean	Optional	When true, returns only flagged/screened transactions
transaction_type	string	Optional	Filter by type: credit or debit

Example

curl

curl -X GET "https://api.banklyze.com/v1/deals/42/transactions?page=1&per_page=50" \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "data": [
    {
      "id": 201,
      "date": "2026-01-03",
      "description": "ACH DEPOSIT - STRIPE PAYMENTS",
      "amount": 4250.00,
      "balance": 32750.00,
      "transaction_type": "credit",
      "is_nsf_fee": false,
      "is_overdraft_fee": false,
      "is_large_deposit": true,
      "is_large_strange": false,
      "is_repeat_charge": false,
      "is_suspicious": false,
      "screening_bucket": null,
      "flag_reason": null,
      "document_id": 15
    },
    {
      "id": 202,
      "date": "2026-01-05",
      "description": "ACH DEBIT - MERCHANT CASH ADVANCE REPAY",
      "amount": -1250.00,
      "balance": 31500.00,
      "transaction_type": "debit",
      "is_nsf_fee": false,
      "is_overdraft_fee": false,
      "is_large_deposit": false,
      "is_large_strange": false,
      "is_repeat_charge": true,
      "is_suspicious": false,
      "screening_bucket": "repeat_charge",
      "flag_reason": "Daily recurring debit pattern",
      "document_id": 15
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 243,
    "total_pages": 5
  }
}

Deal Notes

Deal notes are free-text annotations attached to a deal by underwriters or team members. Notes are used to record manual verification steps, applicant communications, and other contextual information that supports the underwriting decision. Notes are append-only and permanently stored in the deal audit record.

Append a new note to a deal. Notes are timestamped and attributed to the provided author name. There is no limit on the number of notes per deal.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Request Body

Name	Type	Required	Description
content	string	Required	Note body text (max 10,000 characters)
author	string	Optional	Display name of the note author. Defaults to the API key label if not provided.

Example

curl

curl -X POST https://api.banklyze.com/v1/deals/42/notes \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Verified bank statements with applicant. Owner confirmed large Jan deposit was from equipment sale — not revenue.",
    "author": "Jane D."
  }'

Response

Response — 201 Created

{
  "id": 7,
  "deal_id": 42,
  "content": "Verified bank statements with applicant. Owner confirmed large Jan deposit was from equipment sale — not revenue.",
  "author": "Jane D.",
  "created_at": "2026-02-15T15:30:00Z"
}

Retrieve all notes attached to a deal, ordered chronologically (oldest first). Notes are returned in a paginated list.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Query Parameters

Name	Type	Required	Description
page	integer	Default: 1	Page number
per_page	integer	Default: 25	Results per page (max 100)

Example

curl

curl -X GET https://api.banklyze.com/v1/deals/42/notes \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "data": [
    {
      "id": 7,
      "deal_id": 42,
      "content": "Verified bank statements with applicant. Owner confirmed large Jan deposit was from equipment sale — not revenue.",
      "author": "Jane D.",
      "created_at": "2026-02-15T15:30:00Z"
    },
    {
      "id": 8,
      "deal_id": 42,
      "content": "Called references. Two trade vendors confirmed 3+ year relationship.",
      "author": "Mike R.",
      "created_at": "2026-02-16T09:10:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 2,
    "total_pages": 1
  }
}