# Start a deal application
Create a business and start its Deal application for the receiving organisation, then complete and submit it through the API or let the client finish the form. This flow supports both internal integrations and external referrers sending business and application data.
**The result:** business creation starts a Deal and its empty application. You then read that application’s contract and save answers in a separate request. The recipient is the Portal associated with the API key. Creation does not submit the application or select a different lender.
To collect general information before choosing a recipient, use [client intake](https://docs.staging.levr.ai/guides/source-client-intake.md). [Compare starting experiences](https://docs.staging.levr.ai/guides/index.md).
Already have a business from a **Business profile only** source? [Add this setup to the existing business](https://docs.staging.levr.ai/guides/source-business.md#continue-from-the-baseline), then continue with the application completion guide.
## 1. Prepare the source
A **Lead source** chooses how incoming businesses get started. The API calls it a source channel; pass its ID as `source_channel_id` when creating a business. Its settings determine whether business creation also starts an application. Application answers are always saved separately.
The **receiving Portal** is the workspace associated with your API key. Ask its administrator or your integration contact for:
- An API source ID (`srcch_…`) configured as **Start with an application to [receiving Portal name]**, plus a link to that source in the Portal.
- Your environment’s API origin and a Portal API key scoped to the source with `lead_submissions:write` and `deal_applications:write`.
- Confirmation that the source is ready, its selected Deal application is published, and the Portal has a default business pipeline and stage. If the source uses a Deal package, that package determines the form.
Configure the source if you have Portal access
With permission to manage the source, open the Lead source, then **Overview → Getting started → Change setup**, and choose **Start with an application to [receiving Portal name]**. For a new source, choose **API integration** when creating it. Enabling this option requires a lender receiving profile and permission for the Portal to receive direct applications. Publish the selected Deal application; if the source uses a Deal package, that package determines the form.
The source’s **API setup** section contains its ID and integration instructions. If a choice is locked, follow the restriction message and contact your administrator. A source-scoped key can also discover its IDs through the [API root](https://docs.staging.levr.ai/rest-api.md).
Create the source through the API instead
With `source_channels:write`, POST the following body to `/v1/source-channels/` with your bearer key and a new `Idempotency-Key`. Save the returned `id` as `SOURCE_ID`. Check `readiness` in the response to confirm that the source’s form and routing are ready.
```json
{"name":"Website enquiries","starting_experience":"deal_application"}
```
`starting_experience` is required when creating a source. To find an existing source, use [List Lead sources](https://docs.staging.levr.ai/rest-api-reference/businesses/list-business-source-channels.md) with `source_channels:read`.
## 2. Check the source setup
Every request uses `Authorization: Bearer `. Keep the key on your server; [Get started](https://docs.staging.levr.ai/rest-api.md) shows this environment's API address. The examples use illustrative IDs and abbreviated responses.
```http
GET /v1/source-channels/srcch_example/
```
**Response excerpt · 200:**
```json
{
"starting_experience": "deal_application",
"readiness": { "is_ready": true }
}
```
If the experience differs or the source is not ready, ask the receiving Portal's administrator to resolve the returned `readiness.message` before creating records. This check confirms that the source can create the business and application. Later, the application's own readiness check confirms that its answers, documents, and delivery setup are ready for submission.
## 3. Create the business and its Deal
Send the business and primary contact to the business endpoint. `source_channel_id` selects the receiving source's routing and starting experience.
Use your system's unique event ID as the idempotency key. Retain the exact body and key for retries; an identical retry returns the original result, while a new key can create another business.
```http
POST /v1/businesses/
Content-Type: application/json
Idempotency-Key: website-lead-12345-business
```
```json
{
"source_channel_id": "srcch_example",
"business": {
"name": "Cedar Ridge Engineering Ltd.",
"primary_contact_name": "Maya Chen",
"primary_contact_email": "maya@example.com"
},
"invite_client": false
}
```
`invite_client: false` creates the records without emailing a client workspace invitation. `true` sends that invitation during creation; omission or `null` follows the source's invitation setting. To email a link directly to the application after prefilling it, use the editable application link described in the next step.
**Response excerpt · 201:**
```json
{
"business": { "id": "biz_example" },
"starting_experience": "deal_application",
"deal": { "id": "deal_example" },
"deal_application": {
"id": "dapp_example",
"url": "https://YOUR_API_HOST/v1/deal-applications/dapp_example/",
"contract_url": "https://YOUR_API_HOST/v1/deal-applications/dapp_example/contract/",
"answers_url": "https://YOUR_API_HOST/v1/deal-applications/dapp_example/answers/"
}
}
```
Store these IDs and URLs. The business, Deal, and application are separate resources. The application is empty and has not been submitted; creation does not accept application answers. If the response includes `invitation_url`, treat it as private client access.
## 4. Complete and submit the Deal
Continue with [Complete and submit a Deal](https://docs.staging.levr.ai/guides/deal-application.md), using the returned `deal_application.url`. That guide walks through:
- Reading the selected form and saving or editing answers.
- Uploading documents to the correct question.
- Emailing the client a branded form to complete and submit, or checking readiness and submitting through the API.
- Subscribing to submission and status updates through webhooks.
Your existing `deal_applications:write` permission covers reading, editing, and submitting this application. Emailing a form link additionally requires `deal_application_sharing:write`; following the Deal's pipeline stage requires `deals:read`.
For an application to the receiving Portal itself, its published Portal delivery method submits the existing Deal. No extra email or connector delivery method is required. Submission updates the application status and triggers the configured notifications and webhooks.
The same steps apply to a Deal created from a Project match. There is no second application to create or copy. In the receiving Portal, open **Deals** and find **Cedar Ridge Engineering Ltd.** to review the application.
## If a step fails
| Response | Next action |
| --- | --- |
| `401`, `403`, or record not found | Check the environment, ID, key permissions, and source scope. |
| `409 source_channel_not_ready` | Ask the administrator to resolve the reported source setup problem, then read the source again. |
| `409` on a retry | Reuse a key only for the identical command; check the body and preconditions. |
| Validation error | Correct the named field against the creation schema. |
Save progress after each step. If an answer write fails later, continue with the saved application ID rather than creating another business.