Lev Deals API

openapi: 3.1.0
info:
  title: Lev Account & Team Deals API
  version: 2026-03
  description: Build on Lev with AI-friendly API docs, agent guides, and production integration recipes.
servers:
- url: https://api.lev.com
  description: Production API
tags:
- name: Deals
paths:
  /api/external/v2/deals:
    get:
      operationId: getDeals
      summary: List deals with pagination, filtering, and sorting
      description: 'List deals with pagination, filtering, and sorting


        Docs page: https://www.lev.com/docs/build/deals'
      tags:
      - Deals
      parameters:
      - name: limit
        in: query
        required: false
        description: Results per page (1–200, default 50)
        schema:
          type: integer
      - name: cursor
        in: query
        required: false
        description: Cursor for next page (mutually exclusive with sort)
        schema:
          type: string
      - name: offset
        in: query
        required: false
        description: Offset for pagination (requires sort)
        schema:
          type: integer
      - name: sort
        in: query
        required: false
        description: 'Sort fields: title, loan_amount, created_at, updated_at. Prefix with - for descending'
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated fields to include (id always included)
        schema:
          type: string
      - name: include
        in: query
        required: false
        description: 'Sub-resources to embed: financials, properties, team, pipelines'
        schema:
          type: string
      - name: filter[loan_type]
        in: query
        required: false
        description: Filter by loan type enum name, such as heavy_bridge or permanent
        schema:
          $ref: '#/components/schemas/LoanType'
      - name: filter[transaction_type]
        in: query
        required: false
        description: Filter by transaction type enum name, such as acquisition or refinance
        schema:
          $ref: '#/components/schemas/TransactionType'
      - name: filter[business_plan]
        in: query
        required: false
        description: Filter by business plan enum name
        schema:
          $ref: '#/components/schemas/BusinessPlanType'
      - name: filter[archived]
        in: query
        required: false
        description: Filter by archived state. Omit to return both active and archived deals; pass true for only archived, false for only active
        schema:
          type: boolean
      - name: filter[loan_amount][gte]
        in: query
        required: false
        description: Minimum loan amount
        schema:
          type: number
      - name: filter[loan_amount][lte]
        in: query
        required: false
        description: Maximum loan amount
        schema:
          type: number
      - name: filter[created_at][gte]
        in: query
        required: false
        description: Created after (ISO 8601)
        schema:
          type: string
      - name: filter[created_at][lte]
        in: query
        required: false
        description: Created before (ISO 8601)
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Deal'
                  pagination:
                    type: object
        '400':
          description: cursor and sort cannot be combined; use offset pagination when sorting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
      security:
      - bearerAuth: []
      x-lev-docs-page: https://www.lev.com/docs/build/deals
      x-lev-headers:
      - 'Authorization: Bearer <token>'
      - 'X-Origin-App: <client-name>'
    post:
      operationId: postDeals
      summary: Create a new deal
      description: 'Create a new deal


        Docs page: https://www.lev.com/docs/build/deals'
      tags:
      - Deals
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - title
              type: object
              properties:
                title:
                  type: string
                  description: Deal title (1–255 characters)
                loan_amount:
                  type: number
                  description: Requested loan amount
                loan_type:
                  $ref: '#/components/schemas/LoanType'
                  description: Loan type enum name, such as construction, heavy_bridge, or permanent
                transaction_type:
                  $ref: '#/components/schemas/TransactionType'
                  description: Transaction type enum name, such as acquisition, refinance, or new_construction
                business_plan:
                  $ref: '#/components/schemas/BusinessPlanType'
                  description: 'Business plan enum name: stabilized, value_add, construction, or land'
                description:
                  type: string
                  description: Deal description
                estimated_close_date:
                  type: string
                  description: Estimated close date (ISO 8601)
                pipeline_ids:
                  type: array
                  items:
                    type: integer
                  description: Pipeline IDs to add the deal to
                deal_financials:
                  $ref: '#/components/schemas/DealFinancialsWrite'
                  description: Deal-level financial fields to create with the deal
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  data:
                    $ref: '#/components/schemas/Deal'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '422':
          description: title is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
      security:
      - bearerAuth: []
      x-lev-docs-page: https://www.lev.com/docs/build/deals
      x-lev-headers:
      - 'Authorization: Bearer <token>'
      - 'X-Origin-App: <client-name>'
      - 'Content-Type: application/json'
      - 'Idempotency-Key: <uuid>'
  /api/external/v2/deals/{deal_id}:
    get:
      operationId: getDealsDealId
      summary: Get a single deal by ID
      description: 'Get a single deal by ID


        Docs page: https://www.lev.com/docs/build/deals'
      tags:
      - Deals
      parameters:
      - name: deal_id
        in: path
        required: true
        description: The deal ID
        schema:
          type: integer
      - name: include
        in: query
        required: false
        description: 'Sub-resources to embed: financials, properties, team, pipelines'
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated fields to include
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  data:
                    $ref: '#/components/schemas/Deal'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Deal not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
      security:
      - bearerAuth: []
      x-lev-docs-page: https://www.lev.com/docs/build/deals
      x-lev-headers:
      - 'Authorization: Bearer <token>'
      - 'X-Origin-App: <client-name>'
    patch:
      operationId: patchDealsDealId
      summary: Update a deal (partial update)
      description: 'Update a deal (partial update)


        Docs page: https://www.lev.com/docs/build/deals'
      tags:
      - Deals
      parameters:
      - name: deal_id
        in: path
        required: true
        description: The deal ID
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: Deal title (min 1 character)
                loan_amount:
                  type: number
                  description: Requested loan amount
                loan_type:
                  $ref: '#/components/schemas/LoanType'
                  description: Loan type enum name
                transaction_type:
                  $ref: '#/components/schemas/TransactionType'
                  description: Transaction type enum name
                business_plan:
                  $ref: '#/components/schemas/BusinessPlanType'
                  description: Business plan enum name
                description:
                  type: string
                  description: Deal description
                estimated_close_date:
                  type: string
                  description: Estimated close date (ISO 8601)
                deal_financials:
                  $ref: '#/components/schemas/DealFinancialsWrite'
                  description: Deal-level financial fields to update
              minProperties: 1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  data:
                    $ref: '#/components/schemas/Deal'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Deal not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
      security:
      - bearerAuth: []
      x-lev-docs-page: https://www.lev.com/docs/build/deals
      x-lev-headers:
      - 'Authorization: Bearer <token>'
      - 'X-Origin-App: <client-name>'
      - 'Content-Type: application/json'
    delete:
      operationId: deleteDealsDealId
      summary: Archive (soft-delete) a deal
      description: 'Archive (soft-delete) a deal


        Docs page: https://www.lev.com/docs/build/deals'
      tags:
      - Deals
      parameters:
      - name: deal_id
        in: path
        required: true
        description: The deal ID
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  data:
                    $ref: '#/components/schemas/BooleanDeleteResult'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Deal not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
      security:
      - bearerAuth: []
      x-lev-docs-page: https://www.lev.com/docs/build/deals
      x-lev-headers:
      - 'Authorization: Bearer <token>'
      - 'X-Origin-App: <client-name>'
      - 'Content-Type: application/json'
  /api/external/v2/deals/{deal_id}/index/search:
    post:
      operationId: postDealsDealIdIndexSearch
      summary: Search canonical indexed deal facts by natural-language context
      description: 'Search canonical indexed deal facts by natural-language context


        Docs page: https://www.lev.com/docs/build/deals'
      tags:
      - Deals
      parameters:
      - name: deal_id
        in: path
        required: true
        description: The deal ID
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - context
              type: object
              properties:
                context:
                  type: string
                  minLength: 1
                  maxLength: 4000
                  description: Natural-language search context. Be specific about the metric or topic you want.
                min_score:
                  type: number
                  minimum: 0
                  maximum: 1
                  default: 0.3
                  description: Minimum similarity threshold from 0 to 1.
                limit:
                  type: integer
                  minimum: 1
                  maximum: 200
                  default: 20
                  description: Maximum ranked facts to return. Values are clamped to 1-200.
                include_signed_urls:
                  type: boolean
                  default: false
                  description: When true, document-backed source records may include short-lived signed URLs.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DealIndexSearchResult'
                  pagination:
                    type: object
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Deal not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '422':
          description: context must not be blank
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '503':
          description: Deal data search is temporarily unavailable. Try again shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
      security:
      - bearerAuth: []
      x-lev-docs-page: https://www.lev.com/docs/build/deals
      x-lev-headers:
      - 'Authorization: Bearer <token>'
      - 'X-Origin-App: <client-name>'
      - 'Content-Type: application/json'
  /api/external/v2/deals/{deal_id}/index/observations:
    post:
      operationId: postDealsDealIdIndexObservations
      summary: List per-document candidate values behind a deal fact
      description: 'List per-document candidate values behind a deal fact


        Docs page: https://www.lev.com/docs/build/deals'
      tags:
      - Deals
      parameters:
      - name: deal_id
        in: path
        required: true
        description: The deal ID
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              anyOf:
              - required:
                - sot_id
              - required:
                - metric_id
              properties:
                sot_id:
                  type: string
                  pattern: ^[A-Za-z]+:[A-Za-z0-9:_-]+$
                  description: Prefixed SOT id from a prior /index/search result (e.g. 'd:5362', 'a:123:property:690'). At least one of sot_id or metric_id is required.
                metric_id:
                  type: integer
                  minimum: 1
                  description: Numeric metric definition id. Use to fetch every observation for a metric across entities.
                entity_ref:
                  type: string
                  description: Optional entity scoping (e.g. property:690). Intended for use with metric_id; combining with sot_id has no additional effect.
                page:
                  type: integer
                  minimum: 1
                  default: 1
                  description: 1-based page number.
                limit:
                  type: integer
                  minimum: 1
                  maximum: 200
                  default: 20
                  description: Observations per page. Values are clamped to 1-200.
                include_signed_urls:
                  type: boolean
                  default: false
                  description: When true, document-backed source records may include short-lived signed URLs.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DealIndexObservation'
                  pagination:
                    type: object
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Deal not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '422':
          description: Provide at least one of sot_id or metric_id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '503':
          description: Deal observations are temporarily unavailable. Please try again shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
      security:
      - bearerAuth: []
      x-lev-docs-page: https://www.lev.com/docs/build/deals
      x-lev-headers:
      - 'Authorization: Bearer <token>'
      - 'X-Origin-App: <client-name>'
      - 'Content-Type: application/json'
  /api/external/v2/deals/{deal_id}/index/facts:
    patch:
      operationId: patchDealsDealIdIndexFacts
      summary: Update a single canonical deal fact value
      description: 'Update a single canonical deal fact value


        Docs page: https://www.lev.com/docs/build/deals'
      tags:
      - Deals
      parameters:
      - name: deal_id
        in: path
        required: true
        description: The deal ID
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - sot_id
              type: object
              oneOf:
              - required:
                - value
              - required:
                - observation_id
              properties:
                sot_id:
                  type: string
                  pattern: ^[A-Za-z]+:[A-Za-z0-9:_-]+$
                  description: Prefixed SOT id from a prior /index/search result (e.g. 'd:5362', 'a:123:property:690'). Identifies the fact to update.
                value:
                  type: string
                  description: Free-text replacement value. Provide exactly one of value or observation_id.
                observation_id:
                  type: integer
                  minimum: 1
                  description: Observation id to promote as the new canonical value. Returned by /index/observations and preserves source document, page range, and confidence.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  data:
                    $ref: '#/components/schemas/DealIndexFact'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Deal not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '422':
          description: Provide exactly one of value or observation_id; Metric is not editable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '503':
          description: Deal fact update is temporarily unavailable. Please try again shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
      security:
      - bearerAuth: []
      x-lev-docs-page: https://www.lev.com/docs/build/deals
      x-lev-headers:
      - 'Authorization: Bearer <token>'
      - 'X-Origin-App: <client-name>'
      - 'Content-Type: application/json'
    post:
      operationId: postDealsDealIdIndexFacts
      summary: Record one or more user-supplied metric values on a deal
      description: 'Record one or more user-supplied metric values on a deal


        Docs page: https://www.lev.com/docs/build/deals


        Documented response: `results` reports the outcome of each submitted value in request order; `metric_sot_values` aggregates the SOTs that were written. Each `results[].sot` has the same shape as a `metric_sot_values` entry.'
      tags:
      - Deals
      parameters:
      - name: deal_id
        in: path
        required: true
        description: The deal ID
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - values
              properties:
                values:
                  type: array
                  minItems: 1
                  description: One or more metric values to record. Must contain at least one item.
                  items:
                    type: object
                    required:
                    - metric_id
                    - value
                    properties:
                      metric_id:
                        type: integer
                        minimum: 1
                        description: Metric definition id from /index/metric-definitions.
                      value:
                        type: string
                        minLength: 1
                        description: User-supplied value to record. Must not be blank.
                      entity_ref:
                        type: string
                        nullable: true
                        description: Entity to attach the value to, from /index/entities (e.g. 'property:690'). Must match the metric's entity type.
                      group_ref:
                        type: string
                        nullable: true
                        description: Groups several submitted values under the same not-yet-created entity. Use only when no entity_ref is available.
      responses:
        '200':
          description: '`results` reports the outcome of each submitted value in request order; `metric_sot_values` aggregates the SOTs that were written. Each `results[].sot` has the same shape as a `metric_sot_values` entry.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  data:
                    $ref: '#/components/schemas/DealIndexFactInsertResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Deal not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '422':
          description: values must contain at least one item; value must not be blank
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '503':
          description: Deal fact insert is temporarily unavailable. Please try again shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
      security:
      - bearerAuth: []
      x-lev-docs-page: https://www.lev.com/docs/build/deals
      x-lev-headers:
      - 'Authorization: Bearer <token>'
      - 'X-Origin-App: <client-name>'
      - 'Content-Type: application/json'
  /api/external/v2/deals/{deal_id}/index/metric-definitions:
    get:
      operationId: getDealsDealIdIndexMetricDefinitions
      summary: List the metric definitions that can be recorded on a deal
      description: 'List the metric definitions that can be recorded on a deal


        Docs page: https://www.lev.com/docs/build/deals'
      tags:
      - Deals
      parameters:
      - name: deal_id
        in: path
        required: true
        description: The deal ID
        schema:
          type: integer
      - name: metric_label
        in: query
        required: false
        description: Case-insensitive search term to filter by metric label (for example, noi).
        schema:
          type: string
      - name: category_id
        in: query
        required: false
        description: Filter to a single metric category id (greater than 0).
        schema:
          type: integer
      - name: page
        in: query
        required: false
        description: 1-based page number. Defaults to 1.
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Metric definitions per page. Defaults to 100 and is clamped to 1-200.
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DealIndexMetricDefinition'
                  pagination:
                    type: object
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Deal not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '422':
          description: limit must be an integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '503':
          description: Deal metric definitions are temporarily unavailable. Please try again shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
      security:
      - bearerAuth: []
      x-lev-docs-page: https://www.lev.com/docs/build/deals
      x-lev-headers:
      - 'Authorization: Bearer <token>'
      - 'X-Origin-App: <client-name>'
  /api/external/v2/deals/{deal_id}/index/entities:
    get:
      operationId: getDealsDealIdIndexEntities
      summary: List the entities you can attach recorded facts to
      description: 'List the entities you can attach recorded facts to


        Docs page: https://www.lev.com/docs/build/deals'
      tags:
      - Deals
      parameters:
      - name: deal_id
        in: path
        required: true
        description: The deal ID
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  data:
                    type: array
                

# --- truncated at 32 KB (101 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lev/refs/heads/main/openapi/lev-deals-api-openapi.yml