Build

Search Index

Search canonical indexed deal facts and their source documents in the Lev API.

Updated September 2026

POST/api/external/v2/deals/{deal_id}/index/search

Search canonical indexed deal facts by natural-language context

Use Index search when you need source-backed facts that may live in deal attachments or normalized underwriting data. It complements GET /deals/{deal_id}: use GET /deals/{deal_id} for structured deal fields, then use Index search for targeted questions about metrics, loan terms, proceeds, rent roll, occupancy, sponsor background, valuations, capex, dates, and source documents.

The endpoint searches Metric SOT / Index data for one deal. It does not return an exhaustive full Index export.

Path parameters

deal_idintegerrequired

The deal ID

Request body

contextstringrequired

Natural-language search context (1-4000 characters). Be specific about the metric or topic you want.

min_scorenumber

Minimum similarity threshold from 0 to 1. Defaults to 0.3.

limitinteger

Maximum ranked facts to return. Defaults to 20 and is clamped to 1-200.

include_signed_urlsboolean

When true, document-backed source records may include short-lived signed URLs for inspection or download.

curl -X POST "https://api.lev.com/api/external/v2/deals/101/index/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "context": "in-place NOI and source documents",
    "min_score": 0.3,
    "limit": 5,
    "include_signed_urls": false
  }'

Response (200):

{
  "request_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "timestamp": "2026-05-06T15:30:45Z",
  "data": [
    {
      "id": "1",
      "sot_id": 1,
      "metric_key": "deal_financials.in_place_noi",
      "metric_id": 42,
      "metric_label": "In-place NOI",
      "value_text": "$1,250,000",
      "value_type": "currency",
      "context": "The appraisal reports trailing twelve month NOI.",
      "summary": "In-place NOI is $1.25M based on the appraisal.",
      "period_type": "point_in_time",
      "period_value": null,
      "entity_type": "deal",
      "entity_id": null,
      "entity_ref": "deal:123",
      "group_ref": null,
      "category_id": 5,
      "category_label": "Deal Financials",
      "needs_review": false,
      "score": 0.87,
      "source": {
        "type": "document",
        "document_id": 99,
        "document_type": "appraisal",
        "file_name": "appraisal.pdf",
        "file_extension": ".pdf",
        "pages": [3, 12],
        "observation_count": 3,
        "signed_url": null
      }
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 5,
    "offset": 0,
    "has_more": false
  }
}

When include_signed_urls=true, document-backed results may include source.signed_url. Signing failures are non-fatal: the result stays in the response with source.signed_url=null and a typed source.signed_url_error such as signing_failed, missing_document_id, or invalid_document_id.

422validation_error

context must not be blank— The request body omits context or sends only whitespace

401unauthorized

Authentication required— Missing or invalid Authorization header

404not_found

Deal not found— The deal_id doesn't exist or isn't accessible to the authenticated user

503service_unavailable

Deal data search is temporarily unavailable. Try again shortly.— The indexed-data search service is unavailable