Deals | Lev Platform Docs

Integration Summary

When to use

Create, read, update, and delete deals.
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

See the request body tables below or /platform/openapi.json for the machine-readable schema surface.

Response schema

Responses use the standard request_id/timestamp/data envelope. This page documents these object schemas: Deal Object.

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

See /rate-limits. Page intentionally through list endpoints and apply backoff on 429 responses.

Examples

curl, TypeScript, Python

Starter example: GET /api/external/v2/deals

bash

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

Connect your API key to explore

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

GET/api/external/v2/deals

Query Parameters

limit

include

fields

sort

https://api.levcapital.com/api/external/v2/deals?limit=5

Overview

The deals endpoints support full CRUD operations with filtering, sorting, pagination, sparse fieldsets, and optional sub-resource includes.

Endpoint	Description
`GET /deals`	List deals with filtering and pagination
`GET /deals/{id}`	Get a single deal
`POST /deals`	Create a new deal
`PATCH /deals/{id}`	Update a deal
`DELETE /deals/{id}`	Archive (soft-delete) a deal

List Deals

GET/api/external/v2/deals

List deals with pagination, filtering, and sorting

Query parameters

Parameter	Type	Required	Description
`limit`	`integer`	Optional	Results per page (1–200, default 50)
`cursor`	`string`	Optional	Cursor for next page (mutually exclusive with sort)
`offset`	`integer`	Optional	Offset for pagination (requires sort)
`sort`	`string`	Optional	Sort fields: title, loan_amount, created_at, updated_at. Prefix with - for descending
`fields`	`string`	Optional	Comma-separated fields to include (id always included)
`include`	`string`	Optional	Sub-resources to embed: financials, properties, team
`filter[loan_type]`	`string`	Optional	Filter by loan type (acquisition, refinance, etc.)
`filter[transaction_type]`	`string`	Optional	Filter by transaction type
`filter[business_plan]`	`string`	Optional	Filter by business plan
`filter[loan_amount][gte]`	`number`	Optional	Minimum loan amount
`filter[loan_amount][lte]`	`number`	Optional	Maximum loan amount
`filter[created_at][gte]`	`string`	Optional	Created after (ISO 8601)
`filter[created_at][lte]`	`string`	Optional	Created before (ISO 8601)

bash

curl -X GET "https://api.levcapital.com/api/external/v2/deals?limit=10&include=financials&sort=-created_at" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200):

json

{
  "request_id": "...",
  "timestamp": "2026-03-20T15:30:45Z",
  "data": [
    {
      "id": 101,
      "title": "123 Main St Acquisition",
      "loan_amount": 5000000.0,
      "loan_type": "acquisition",
      "transaction_type": "purchase",
      "business_plan": "value_add",
      "description": "Mixed-use acquisition in downtown",
      "estimated_close_date": "2026-06-01",
      "close_date": null,
      "owner_account_id": 56,
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-03-10T14:30:00Z",
      "financials": {
        "id": 201,
        "noi": 450000.0,
        "purchase_price": 6500000.0,
        "appraised_value": 7000000.0,
        "ltv": 0.714,
        "dscr": 1.25
      }
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

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": {}
  }
}

400bad_request

When: Both cursor and sort query parameters are provided

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "error": {
    "status": 400,
    "type": "bad_request",
    "message": "cursor and sort cannot be combined; use offset pagination when sorting",
    "details": {}
  }
}

Get Deal

GET/api/external/v2/deals/{deal_id}

Get a single deal by ID

Path parameters

Parameter	Type	Required	Description
`deal_id`	`integer`	Required	The deal ID

Query parameters

Parameter	Type	Required	Description
`include`	`string`	Optional	Sub-resources to embed: financials, properties, team
`fields`	`string`	Optional	Comma-separated fields to include

Response (200):

json

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2026-03-20T15:30:45Z",
  "data": {
    "id": 101,
    "title": "123 Main St Acquisition",
    "loan_amount": 5000000.0,
    "loan_type": "acquisition",
    "transaction_type": "purchase",
    "business_plan": "value_add",
    "description": "Mixed-use acquisition in downtown Chicago",
    "estimated_close_date": "2026-06-01",
    "close_date": null,
    "owner_account_id": 56,
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-03-10T14:30:00Z"
  }
}

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": {}
  }
}

Create Deal

POST/api/external/v2/deals

Create a new deal

Supports the Idempotency-Key header to prevent duplicate creation.

Request body

Parameter	Type	Required	Description
`title`	`string`	Required	Deal title (1–255 characters)
`loan_amount`	`number`	Optional	Requested loan amount
`loan_type`	`string`	Optional	Loan type (acquisition, refinance, construction, etc.)
`transaction_type`	`string`	Optional	Transaction type (purchase, refinance, etc.)
`business_plan`	`string`	Optional	Business plan (stabilized, value_add, etc.)
`description`	`string`	Optional	Deal description
`estimated_close_date`	`string`	Optional	Estimated close date (ISO 8601)
`pipeline_ids`	`integer[]`	Optional	Pipeline IDs to add the deal to

bash

curl -X POST "https://api.levcapital.com/api/external/v2/deals" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "title": "456 Oak Ave Refinance",
    "loan_amount": 3500000,
    "loan_type": "refinance",
    "transaction_type": "refinance"
  }'

Response (201):

json

{
  "request_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "timestamp": "2026-03-20T15:30:45Z",
  "data": {
    "id": 205,
    "title": "456 Oak Ave Refinance",
    "loan_amount": 3500000.0,
    "loan_type": "refinance",
    "transaction_type": "refinance",
    "business_plan": null,
    "description": null,
    "estimated_close_date": null,
    "close_date": null,
    "owner_account_id": 56,
    "created_at": "2026-03-20T15:30:45Z",
    "updated_at": "2026-03-20T15:30:45Z"
  }
}

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": {}
  }
}

422validation_error

When: Missing the required title field in the request body

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "error": {
    "status": 422,
    "type": "validation_error",
    "message": "title is required",
    "details": {}
  }
}

Update Deal

PATCH/api/external/v2/deals/{deal_id}

Update a deal (partial update)

Path parameters

Parameter	Type	Required	Description
`deal_id`	`integer`	Required	The deal ID

All request body fields are optional. Only provided fields are updated.

Request body

Parameter	Type	Required	Description
`title`	`string`	Optional	Deal title (min 1 character)
`loan_amount`	`number`	Optional	Requested loan amount
`loan_type`	`string`	Optional	Loan type
`transaction_type`	`string`	Optional	Transaction type
`business_plan`	`string`	Optional	Business plan
`description`	`string`	Optional	Deal description
`estimated_close_date`	`string`	Optional	Estimated close date (ISO 8601)

Response (200):

json

{
  "request_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "timestamp": "2026-03-20T15:30:45Z",
  "data": {
    "id": 101,
    "title": "123 Main St Acquisition",
    "loan_amount": 7500000.0,
    "loan_type": "acquisition",
    "transaction_type": "purchase",
    "business_plan": "value_add",
    "description": "Mixed-use acquisition in downtown Chicago — updated loan amount",
    "estimated_close_date": "2026-07-15",
    "close_date": null,
    "owner_account_id": 56,
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-03-20T15:30:45Z"
  }
}

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": {}
  }
}

Delete Deal

DELETE/api/external/v2/deals/{deal_id}

Archive (soft-delete) a deal

Path parameters

Parameter	Type	Required	Description
`deal_id`	`integer`	Required	The deal ID

Response (200):

json

{
  "request_id": "...",
  "timestamp": "2026-03-20T15:30:45Z",
  "data": {
    "deleted": true
  }
}

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": {}
  }
}

Deal Object

Field	Type	Description
`id`	integer	Unique deal identifier
`title`	string\|null	Deal title
`loan_amount`	number\|null	Requested loan amount
`loan_type`	string\|null	Loan type (acquisition, refinance, construction, etc.)
`transaction_type`	string\|null	Transaction type
`business_plan`	string\|null	Business plan
`description`	string\|null	Deal description
`estimated_close_date`	string\|null	Estimated close date (ISO 8601)
`close_date`	string\|null	Actual close date (ISO 8601)
`owner_account_id`	integer\|null	Owning account ID
`created_at`	string\|null	Creation timestamp (ISO 8601)
`updated_at`	string\|null	Last update timestamp (ISO 8601)
`financials`	object\|null	Included when `?include=financials` (see Deal Financials)
`properties`	array\|null	Included when `?include=properties` (see Deal Properties)
`team`	array\|null	Included when `?include=team` (see Deal Team)

Build on Lev's Platform Authentication Quickstart API Keys Pagination

Integration Summary

Starter example: GET /api/external/v2/deals

Overview

List Deals

Query parameters

Error responses

Get Deal

Path parameters

Query parameters

Error responses

Create Deal

Request body

Error responses

Update Deal

Path parameters

Request body

Error responses

Delete Deal

Path parameters

Error responses

Deal Object

Related Articles