# Deals

Follow a business's funding request to a recipient, manage its stage, and open its application.

Base URL: https://api.levr.ai/v1

Authentication: Bearer — Portal API key

[REST guide](https://docs.levr.ai/rest-api.md) · [OpenAPI specification](https://docs.levr.ai/generated/openapi.json)

OpenAPI defines exact REST schemas. Each record’s Application Contract defines its current questions and accepted answers.

## Create a deal

A deal tracks a business's funding request to one recipient. Its Deal application collects the answers and documents that recipient needs.

If you already know who should receive the Deal, use [List Deal recipients](https://docs.levr.ai/rest-api-reference/deal-recipients/list-deal-recipients.md) (`GET /deal-recipients/`). It includes your own team, Marketplace lenders, connected partners, and custom recipients available to your Portal. This needs Deals read access. Search by name and follow `next_cursor` for more results. Choose a recipient with `can_create_deal: true`; otherwise, `unavailable_reason` explains what needs attention.

If you need recommendations, start with [Matchmaking](https://docs.levr.ai/guides/matchmaking.md) and review the results before choosing a recipient.

Use [Create a Deal](https://docs.levr.ai/rest-api-reference/deals/create-deal.md) (`POST /deals/`) with the Business ID and `recipient_id`. Copy the recipient's `id` from the recipient list, or `recipient.id` from a matchmaking result. For a Deal your team will process, choose your own team from the recipient list. Include `project_id` to link a Project belonging to this Business. Match result IDs are for saving your shortlist.

Creation uses the recipient's current published application and your default Deal pipeline, and starts Autofill. The application stays private to your team and is not submitted. Save the returned Deal and application IDs, then [complete the application](https://docs.levr.ai/rest-api-reference/deal-applications/index.md).

Send a unique `Idempotency-Key` with each creation request. Reuse the same key and body when retrying to receive the original Deal. Use a new key only when you intend to create another Deal.

## Complete and follow the deal

Open the linked [Deal application](https://docs.levr.ai/rest-api-reference/deal-applications/index.md) to complete answers, attach documents, use Autofill, check readiness, and submit. A submission receipt does not establish lender acceptance, approval, or funding.

Check the deal name, linked project/application IDs, and pipeline stage. Read the linked records when you need more context to distinguish similarly named deals.

`status` describes application progress. `workflow.stage` describes placement on your Portal's board. Moving a stage does not submit an application or change its application status.

To move a deal on your board, discover stages through `workflow.stages_url` and update the stage with the deal ETag.

## Record an application decision

To decline, mark funded, withdraw, mark timed out, reopen, or record submitted/not-submitted status, follow [Application decisions](https://docs.levr.ai/rest-api-reference/deal-applications/#record-an-application-decision).

## Update participants or the linked project

Deal participants are a complete replacement set. Read its ETag, choose people available in your Portal, and include the primary person in `person_ids`. Null clears the primary designation; an empty set clears participants. Read back the result.

To move a deal to another project, use [Move a Deal to a Project](https://docs.levr.ai/rest-api-reference/deals/set-deal-project.md).


- [List Deals](https://docs.levr.ai/rest-api-reference/deals/list-deals.md): `GET /deals/`

- [Associate an existing Deal with a Project](https://docs.levr.ai/rest-api-reference/deals/set-deal-project.md): `POST /deals/{deal_id}/project/`

- [Create a Deal](https://docs.levr.ai/rest-api-reference/deals/create-deal.md): `POST /deals/`

- [List Deal participants](https://docs.levr.ai/rest-api-reference/deals/list-deal-participants.md): `GET /deals/{deal_id}/participants/`

- [Retrieve a Deal](https://docs.levr.ai/rest-api-reference/deals/retrieve-deal.md): `GET /deals/{deal_id}/`

- [Retrieve Deal financing terms](https://docs.levr.ai/rest-api-reference/deals/retrieve-deal-terms.md): `GET /deals/{deal_id}/terms/`

- [Replace Deal participants](https://docs.levr.ai/rest-api-reference/deals/replace-deal-participants.md): `PUT /deals/{deal_id}/participants/`

- [Update a Deal](https://docs.levr.ai/rest-api-reference/deals/update-deal.md): `PATCH /deals/{deal_id}/`

- [Update Deal financing terms](https://docs.levr.ai/rest-api-reference/deals/update-deal-terms.md): `PATCH /deals/{deal_id}/terms/`

- [Move one Deal to a workflow stage](https://docs.levr.ai/rest-api-reference/deals/move-deal-stage.md): `PATCH /deals/{deal_id}/stage/`