# Lev API

> Lev is the leading platform for commercial real estate (CRE) deal and transaction management. The External API v2 is a RESTful JSON API at `https://api.levcapital.com/api/external/v2`. It powers deal lifecycle management, CRM, AI-powered lender matching, term sheet tracking, and market data across 7,000+ lenders and $50B+ in processed transactions.

## Instructions for LLM Agents

Base URL: `https://api.levcapital.com/api/external/v2`

Authentication: Every request requires two headers:
- `Authorization: Bearer <api_key_or_jwt>` — API keys (prefix `lev_sk_`) are long-lived; JWTs are short-lived via OAuth 2.1 + PKCE.
- `X-Origin-App: <your_app_name>` — identifies the calling application.

For writes, also include:
- `Content-Type: application/json`
- `Idempotency-Key: <uuid>` (recommended, 24-hour expiry)

Response envelope: All responses return `{ request_id, timestamp, data }`. Lists add `{ pagination: { total, limit, cursor|offset, has_more, next_cursor? } }`.

Pagination: Cursor-based by default (stable, no duplicates). Offset-based when `sort` is specified. Default limit: 50, max: 200.

Error handling: Standard HTTP codes. Error body: `{ request_id, error: { code, message } }`. 404 is returned for both missing resources and resources the caller cannot access (no information leakage).

Rate limits: 200 req/min reads, 30 req/min writes, 10 req/min for auth validation.

Resource hierarchy: Deals are the core resource. Financials, properties, team, placements, term sheets, and lender search are sub-resources of a deal. Contacts and companies are account-scoped CRM resources. The lender directory is global (not account-scoped).

When generating code: always use cursor pagination for bulk sync, use `fields` param to minimize payloads, use `include` to avoid N+1 requests, and handle 429 with exponential backoff.

## Machine-Readable Resources

- OpenAPI spec: `/platform/openapi.json`
- Full docs bundle: `/platform/llms-full.txt` (all pages as markdown)
- Per-page markdown: append `.md` to any route, e.g. `/platform/deals.md`
- This file: `/platform/llms.txt`

## Start Here

- [Build on Lev's Platform](https://lev.com/platform/build-on-lev): Choose the fastest path to build on Lev: REST APIs, MCP agents, or production-ready recipes.
- [Lev External API v2](https://lev.com/platform): The API overview for Lev's REST surface, shared response model, and machine-readable developer resources.
- [Quickstart](https://lev.com/platform/getting-started): Make your first successful REST call or MCP connection using two clear happy paths.

## REST API

- [Authentication](https://lev.com/platform/authentication): API key and JWT authentication for the Lev API.
- [API Keys](https://lev.com/platform/api-keys): Create, list, and revoke API keys.
- [Pagination](https://lev.com/platform/pagination): Cursor-based and offset-based pagination patterns.
- [Filtering & Sorting](https://lev.com/platform/filtering-sorting): Filter and sort list endpoint results.
- [Error Handling](https://lev.com/platform/errors): HTTP status codes and error response format.
- [Rate Limits](https://lev.com/platform/rate-limits): Request rate limits and throttling behavior.
- [Deals](https://lev.com/platform/deals): Create, read, update, and delete deals.
- [Deal Financials](https://lev.com/platform/deal-financials): Read deal financial details.
- [Deal Properties](https://lev.com/platform/deal-properties): List properties linked to a deal.
- [Pipelines](https://lev.com/platform/pipelines): Browse pipelines and move deals between stages.
- [Deal Team](https://lev.com/platform/deal-team): View team members assigned to a deal.
- [Placements](https://lev.com/platform/placements): View lender placements on deals.
- [Contacts](https://lev.com/platform/contacts): Create, read, and update CRM contacts.
- [Companies](https://lev.com/platform/companies): Create, read, and update CRM companies.
- [Lender Directory](https://lev.com/platform/lender-directory): Browse lenders and lending programs.
- [Term Sheets](https://lev.com/platform/term-sheets): List and view term sheets for deals.
- [Account & Team](https://lev.com/platform/account): View account information and team members.
- [Market Data](https://lev.com/platform/market-data): Access base rates and asset type reference data.

## MCP / Agents

- [MCP Setup](https://lev.com/platform/mcp-setup): Connect Lev to Cursor, Claude, and other MCP-compatible clients with a predictable setup flow.
- [Agent Workflows](https://lev.com/platform/agent-workflows): Design reliable agent workflows that retrieve the right Lev context, take bounded actions, and stay explainable.
- [Lender Search](https://lev.com/platform/lender-search): Trigger and retrieve AI-powered lender search results, then fold them into a broker or analyst workflow.

## Recipes

- [Data Sync Patterns](https://lev.com/platform/data-sync-patterns): Build reliable backfills and incremental sync jobs using Lev's pagination, filtering, and stable response patterns.
- [Build a Broker Copilot](https://lev.com/platform/broker-copilot): A production-oriented recipe for combining deals, lender search, placements, and term sheets into one broker-facing copilot.

## Endpoint Reference — Quickstart

Docs: https://lev.com/platform/getting-started

`POST /auth/validate-api-key` — Validate an API key and receive authentication details


## Endpoint Reference — Authentication

Docs: https://lev.com/platform/authentication

`POST /auth/validate-api-key` — Validate an API key (unauthenticated endpoint)

## Endpoint Reference — API Keys

Docs: https://lev.com/platform/api-keys

`POST /api-keys` — Create a new API key for the authenticated user
  Body: label* (string)

`GET /api-keys` — List all API keys for the authenticated user Query: limit, offset.

`DELETE /api-keys/{key_id}` — Permanently revoke an API key

## Endpoint Reference — Deals

Docs: https://lev.com/platform/deals

`GET /deals` — List deals with pagination, filtering, and sorting Query: limit, cursor, offset, sort, fields, include, filter[loan_type], filter[transaction_type], filter[business_plan], filter[loan_amount][gte], filter[loan_amount][lte], filter[created_at][gte], filter[created_at][lte].

`GET /deals/{deal_id}` — Get a single deal by ID Query: include, fields.

`POST /deals` — Create a new deal
  Body: title* (string), loan_amount (number), loan_type (string), transaction_type (string), business_plan (string), description (string), estimated_close_date (string), pipeline_ids (integer[])

`PATCH /deals/{deal_id}` — Update a deal (partial update)
  Body: title (string), loan_amount (number), loan_type (string), transaction_type (string), business_plan (string), description (string), estimated_close_date (string)

`DELETE /deals/{deal_id}` — Archive (soft-delete) a deal

## Endpoint Reference — Deal Financials

Docs: https://lev.com/platform/deal-financials

`GET /deals/{deal_id}/financials` — Get financial details for a deal

## Endpoint Reference — Deal Properties

Docs: https://lev.com/platform/deal-properties

`GET /deals/{deal_id}/properties` — List properties associated with a deal

## Endpoint Reference — Pipelines

Docs: https://lev.com/platform/pipelines

`GET /pipelines` — List all pipelines available to your account

`GET /pipelines/{pipeline_id}` — Get a single pipeline with its statuses

`POST /deals/{deal_id}/pipeline` — Move a deal to a pipeline stage
  Body: pipeline_id* (integer), pipeline_status_id (integer)

## Endpoint Reference — Deal Team

Docs: https://lev.com/platform/deal-team

`GET /deals/{deal_id}/team` — List all team members assigned to a deal

## Endpoint Reference — Placements

Docs: https://lev.com/platform/placements

`GET /placements` — List placements with pagination Query: limit, cursor.

`GET /placements/{placement_id}` — Get a single placement by ID

## Endpoint Reference — Contacts

Docs: https://lev.com/platform/contacts

`GET /contacts` — List contacts with pagination Query: limit, cursor, fields.

`GET /contacts/{contact_id}` — Get a single contact by ID

`POST /contacts` — Create a new contact
  Body: contact_type* (string), company_id* (integer), first_name (string), last_name (string), email (string), title (string), department (string), address (string), city (string), state (string), zip (string), linkedin_url (string), is_primary (boolean)

`PATCH /contacts/{contact_id}` — Update a contact

## Endpoint Reference — Companies

Docs: https://lev.com/platform/companies

`GET /companies` — List companies in your account Query: limit, cursor, fields.

`GET /companies/{company_id}` — Get a single company by ID

`POST /companies` — Create a new company
  Body: name* (string), company_type* (string), website (string), address (string), city (string), state (string), zip (string), org_id (integer), linkedin_url (string)

`PATCH /companies/{company_id}` — Update a company

## Endpoint Reference — Lender Directory

Docs: https://lev.com/platform/lender-directory

`GET /lenders/directory` — Browse the lender directory Query: name, filter[state], sort, fields, limit, cursor.

`GET /lenders/{org_id}` — Get detailed lender information including programs

`GET /lenders/{org_id}/programs` — List lending programs for a lender

## Endpoint Reference — Term Sheets

Docs: https://lev.com/platform/term-sheets

`GET /deals/{deal_id}/term-sheets` — List term sheets for a deal Query: limit, cursor.

`GET /deals/{deal_id}/term-sheets/{term_sheet_id}` — Get a single term sheet

## Endpoint Reference — Account & Team

Docs: https://lev.com/platform/account

`GET /me` — Get the authenticated user's profile, account, and platform details

`GET /account/team` — List team members in your account

## Endpoint Reference — Market Data

Docs: https://lev.com/platform/market-data

`GET /market/base-rates` — Get current base rates (SOFR, CMT, Prime, etc.)

`GET /market/asset-types` — Get available asset type definitions


## Endpoint Reference — Lender Search

Docs: https://lev.com/platform/lender-search

`POST /deals/{deal_id}/actions/search-lenders` — Trigger an AI-powered lender search for a deal

`GET /deals/{deal_id}/lender-search` — Get lender search results for a deal Query: limit, offset.


## Optional

- [OpenAPI Spec](https://lev.com/platform/openapi.json): Machine-readable OpenAPI 3.x specification.
- [Full docs bundle](https://lev.com/platform/llms-full.txt): All doc pages as markdown in one file.