Integration Summary

When to use
  • Trigger and retrieve AI-powered lender search results, then fold them into a broker or analyst workflow.
  • Use the read and write examples together so you can validate state before you mutate it.
Required scopes
  • Access is inherited from the connected user or JWT session.
  • Inspect GET /me or the validate-api-key response to confirm the scopes available to the current token.
Headers
  • Authorization: Bearer <token>
  • X-Origin-App: <client-name>
  • Content-Type: application/json on write operations
Request schema
Use the path and query parameter tables below or /platform/openapi.json for the machine-readable schema surface.
Response schema
Responses use the standard request_id/timestamp/data envelope documented in the API overview.
Enums & values
  • Enum-like values and filter operators are documented inline on the page where available.
  • When a value set is account- or tier-dependent, validate against live responses before hard-coding assumptions.
Idempotency
Use Idempotency-Key on retried writes when your client cannot guarantee whether a prior attempt succeeded.
Rate limits
Treat search as a high-value AI action. Poll intentionally and back off on 429 responses.
Examples
curl, TypeScript, Python

Starter example: POST /api/external/v2/deals/{deal_id}/actions/search-lenders

bash
curl -X POST "https://api.levcapital.com/api/external/v2/deals/{deal_id}/actions/search-lenders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Origin-App: my-integration"

Lender Search

Last updated: March 2026

Lender Search is one of the most AI-native workflows in Lev. It turns deal context into a ranked set of lender candidates that can power analyst workflows, broker copilots, and human review queues.
OverviewWorkflow ShapeTriggerResults
Connect your API key to explore

Stored in your browser session only. Never sent to our docs server.

GET/api/external/v2/deals/{deal_id}/lender-search
deal_id*
limit
https://api.levcapital.com/api/external/v2/deals/{deal_id}/lender-search?limit=10

Overview

The lender search workflow is two-step:
  1. Trigger a search (POST) — initiates the AI matching process for a deal
  2. Get results (GET) — retrieves the ranked results once the search is complete
If a recent search already exists for the deal, the trigger endpoint returns cached results immediately.

Workflow Shape

Use lender search as a workflow, not just an endpoint:
  1. Read the deal and any available financial context.
  2. Trigger or reuse lender search for that deal.
  3. Summarize the ranked result set with the deal context that likely drove the ranking.
  4. Hand the shortlist to a human or the next workflow step, such as placement creation or term-sheet review.
POST/api/external/v2/deals/{deal_id}/actions/search-lenders
Trigger an AI-powered lender search for a deal

Path parameters

ParameterTypeRequiredDescription
deal_idintegerRequiredThe deal ID
The request body should be an empty JSON object {}.
Response (200):
json
{
  "request_id": "...",
  "timestamp": "2026-03-20T15:30:45Z",
  "data": {
    "search_id": "abc123",
    "status": "completed",
    "deal_id": 101,
    "message": "Search completed with 25 results"
  }
}
StatusMeaning
completedResults are ready
pendingSearch is in progress — poll the GET endpoint
failedSearch failed

Error responses

401unauthorized

When: Missing or invalid Authorization header

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "error": {
    "status": 401,
    "type": "unauthorized",
    "message": "Authentication required",
    "details": {}
  }
}
404not_found

When: The deal_id doesn't exist or isn't accessible to the authenticated user

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "error": {
    "status": 404,
    "type": "not_found",
    "message": "Deal not found",
    "details": {}
  }
}

Trigger a lender search

bash
curl -X POST "https://api.levcapital.com/api/external/v2/deals/{deal_id}/actions/search-lenders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Origin-App: my-integration"
  -d '{}'

Get Results

GET/api/external/v2/deals/{deal_id}/lender-search
Get lender search results for a deal

Path parameters

ParameterTypeRequiredDescription
deal_idintegerRequiredThe deal ID

Query parameters

ParameterTypeRequiredDescription
limitintegerOptionalResults per page (default 50)
offsetintegerOptionalOffset for pagination
Response (200):
json
{
  "request_id": "...",
  "timestamp": "2026-03-20T15:30:45Z",
  "data": {
    "search_id": "abc123",
    "status": "completed",
    "deal_id": 101,
    "results": [
      {
        "org_id": 500,
        "organization_name": "First National Bank",
        "ai_score": 92,
        "ai_rank_status": "top_match",
        "ai_match_insights": "Strong fit based on asset type and geography",
        "is_connected_lender": true,
        "programs": [
          {
            "id": 10,
            "title": "CRE Bridge Lending",
            "loan_types": ["bridge"],
            "capital_source_type": "balance_sheet",
            "min_loan_amount": 1000000,
            "max_loan_amount": 50000000,
            "asset_types": ["multifamily", "office"],
            "states": ["NY", "NJ", "CT"]
          }
        ]
      }
    ],
    "pagination": {
      "total": 25,
      "limit": 50,
      "offset": 0,
      "has_more": false
    }
  }
}
Each result in the results array contains:
FieldTypeDescription
org_idinteger|nullOrganization ID
organization_namestring|nullLender name
ai_scoreinteger|nullAI match score
ai_rank_statusstring|nullAI ranking status
ai_match_insightsstring|nullAI-generated match reasoning
is_connected_lenderboolean|nullWhether the lender is in your CRM
programsarray|nullMatching lending programs
Each program in the programs array contains:
FieldTypeDescription
idintegerProgram ID
titlestring|nullProgram name
loan_typesstring[]|nullSupported loan types
capital_source_typestring|nullCapital source type
min_loan_amountnumber|nullMinimum loan amount
max_loan_amountnumber|nullMaximum loan amount
asset_typesstring[]|nullSupported asset types
statesstring[]|nullGeographic coverage
Returns 404 if no search has been run for this deal.

Error responses

401unauthorized

When: Missing or invalid Authorization header

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "error": {
    "status": 401,
    "type": "unauthorized",
    "message": "Authentication required",
    "details": {}
  }
}
404not_found

When: The deal_id doesn't exist or no search has been run for this deal

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "error": {
    "status": 404,
    "type": "not_found",
    "message": "Deal not found",
    "details": {}
  }
}

Read the latest lender search results

bash
curl -X GET "https://api.levcapital.com/api/external/v2/deals/{deal_id}/lender-search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Origin-App: my-integration"

Implementation Notes

  • Trigger first, then poll with intention. Do not create aggressive retry loops.
  • Cache the latest search_id and status in your own workflow state when you are orchestrating multiple steps.
  • Treat lender search as recommendation input. Keep the final outreach and placement decisions reviewable by a human.

Related Articles

Build on Lev's PlatformAuthenticationQuickstartAPI KeysPagination