---
title: "Create Deal"
method: POST
path: "/api/external/v2/deals"
tags: ["external-v2-deals"]
---

# Create Deal

`POST /api/external/v2/deals`

Create a new deal.

``body: CreateDealRequest`` lets FastAPI/Pydantic parse and validate the
request body automatically. Missing ``title`` or constraint violations
return 422 before reaching this function.

## Request body

- CreateDealRequest — POST /api/external/v2/deals request body. Exposes a curated subset of deal fields suitable for programmatic deal creation. More fields can be added in future releases without breaking existing integrations.
  - `title` string, required — Deal title (required)
  - `loan_amount` number, nullable — Requested loan amount
  - `priority` 'No priority' | 'Urgent' | 'High' | 'Medium' | 'Low'
  - `loan_type` 'Construction' | 'Heavy Bridge' | 'Light Bridge' | 'Permanent' | 'Land' | 'Predevelopment' | 'TBD'
  - `transaction_type` 'TBD' | 'Acquisition' | 'Refinance' | 'New Construction'
  - `business_plan` 'stabilized' | 'value_add' | 'construction' | 'land'
  - `description` string, nullable — Free-text deal description
  - `estimated_close_date` string, date, nullable — Estimated close date (ISO 8601 date string, e.g. 2025-12-31)
  - `pipeline_ids` integer[], nullable — Pipeline IDs to associate with the deal (max 25). All ids must belong to the caller's account; unknown or cross-account ids return 404. Financing and acquisition pipelines may each appear at most once.
  - `sponsor_private_company_id` integer, nullable — ID of the sponsor company (a PrivateCompany) to link to this deal. Must belong to the caller's account. Linking also adds the sponsor's users to the deal team when the deal is brokered.
  - `properties` CreateDealPropertyInput[], nullable — Properties to attach to the deal at creation time (max 25 per deal — portfolio cap to keep the access check bounded). Each entry either links an existing property (property_id) or inline-creates a new one (address, city, state, zip, asset_type_id, units, square_footage, year_built). Brokers typically know the address before the financing, so this lets a deal be authored in one call instead of a deal-then-property two-step.
    - `property_id` integer, nullable — ID of an existing property to link. Must be reachable from the caller's account (already linked to a deal the account owns). Mutually exclusive with the inline-create fields below.
    - `address` string, nullable — Street address.
    - `city` string, nullable
    - `state` string, nullable — State/province (e.g. 'NY', 'CA').
    - `zip` string, nullable
    - `asset_type_id` integer, nullable — Asset subtype ID — discover via get_asset_types.
    - `units` number, nullable — Unit count (e.g. apartment units).
    - `square_footage` number, nullable — Rentable/leasable area in square feet.
    - `year_built` integer, nullable
  - `deal_financials` CreateDealFinancialsInput — Canonical deal-level financial denominators on POST/PATCH /deals.
    - `purchase_price` number, nullable — Purchase price for LTV (acquisition).
    - `estimated_value` number, nullable — Estimated value for LTV (refinance).
    - `total_cost` number, nullable — Total project cost for construction LTC.
    - `total_cost_basis` number, nullable — Total cost basis for LTC (bridge, etc.).
    - `land_cost` number, nullable — Land cost for construction LTC.

## Response `201`

Successful Response

- DealObjectResponse — OpenAPI schema for GET/POST/PATCH /api/external/v2/deals (object envelope).
  - `request_id` string, required
  - `timestamp` string, required
  - `data` DealResponse, required
    - `id` integer, required
    - `title` string, nullable, required
    - `loan_amount` number, nullable, required
    - `priority` string, required
    - `loan_type` string, nullable, required
    - `transaction_type` string, nullable, required
    - `business_plan` string, nullable, required
    - `description` string, nullable, required
    - `estimated_close_date` string, nullable, required
    - `close_date` string, nullable, required
    - `owner_account_id` integer, nullable, required
    - `sponsor_private_company_id` integer, nullable, required
    - `urls` DealUrlsResponse, required — Borrower-portal deeplinks emitted on every deal payload — keys mirror ``app.utils.url_generator.DEAL_SUBPAGE_PATHS``.
      - `overview` string, required
      - `data` string, required
      - `dataroom` string, required
      - `lenders` string, required
      - `quote_matrix` string, required
      - `vaults` string, required
    - `created_at` string, nullable, required
    - `updated_at` string, nullable, required
    - `archived` boolean, required
    - `archived_at` string, nullable, required
    - `financials` DealFinancialsResponse
      - `id` integer, required
      - `in_place_noi` number, nullable, required
      - `stabilized_noi` number, nullable, required
      - `stabilized_value` number, nullable, required
      - `stabilized_occupancy` number, nullable, required
      - `purchase_price` number, nullable, required
      - `asking_price` number, nullable, required
      - `estimated_value` number, nullable, required
      - `total_cost` number, nullable, required
      - `total_cost_basis` number, nullable, required
      - `capex` number, nullable, required
      - `existing_debt` number, nullable, required
      - `going_in_cap_rate` number, nullable, required
      - `land_cost` number, nullable, required
    - `properties` DealPropertyResponse[], nullable
      - `id` integer, required
      - `name` string, nullable, required
      - `address` string, nullable, required
      - `city` string, nullable, required
      - `state` string, nullable, required
      - `zip` string, nullable, required
      - `asset_type_id` integer, nullable, required
      - `units` integer, nullable, required
      - `square_footage` number, nullable, required
      - `year_built` integer, nullable, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/lev/apis/lev-api.md) · [All operations](https://skmtc.net/lev/apis/lev-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lev/lev-api/revisions/5bfe74cf6f12/schema)