# Collect a client intake application

Create a business, complete its client intake, and submit it to the receiving Portal. This walkthrough works for an internal integration or an external referrer supplying information on a client's behalf.

**The result:** a submitted intake with answers and supporting files, ready for the receiving team's review. Submission notifies the receiving team according to the Portal's notification settings and starts intake preparation when applicable. Business creation alone creates a draft; it does not submit it or create a Deal.

For an application to a specific recipient, use the [Deal application guide](https://docs.staging.levr.ai/guides/source-direct-deal.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** determines how a business gets started. The API calls it a source channel; supply its ID as `source_channel_id`. The receiving Portal is the workspace associated with your API key.

Ask the Portal administrator or your integration contact for:

- An API source (`srcch_…`) configured as **Start with client intake form**, with its intake form published and default business pipeline and stage configured.
- Your environment's [API address](https://docs.staging.levr.ai/rest-api.md) and a key scoped to the source.
- `lead_submissions:write` and `client_intake_applications:write`. The application permission also covers submission. Add `client_intake_sharing:write` to email the form to the client.

<details>
<summary>Find the setup in the Portal</summary>

Open the Lead source, then **Overview → Getting started → Change setup** and choose **Start with client intake form**. Publish the form under **Client intake**. **API setup** contains the source ID and integration instructions. If a choice is locked, follow the restriction message and contact the administrator.

</details>

Examples below use abbreviated responses and illustrative IDs. Use the IDs, URLs, question keys, and ETags returned by your API. Send `Authorization: Bearer <api-key>` on every request, and `Content-Type: application/json` on JSON writes. Keep the key on your server.

```http
GET /v1/source-channels/srcch_example/
```

**Response — relevant fields**

```json
{
  "starting_experience": "client_intake",
  "readiness": { "is_ready": true }
}
```

Continue only when the experience matches and the source is ready. The administrator must resolve reported setup issues first.

## 2. Create the business and intake

Give each write its own stable idempotency key. Retry a failed connection with the same endpoint, body, and key; a new key can create another record.

```http
POST /v1/businesses/
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
}
```

**201 Created — relevant fields**

```json
{
  "business": { "id": "biz_example" },
  "starting_experience": "client_intake",
  "client_intake_application": {
    "id": "ciappl_example",
    "url": "https://YOUR_API_HOST/v1/client-intake-applications/ciappl_example/",
    "contract_url": "https://YOUR_API_HOST/v1/client-intake-applications/ciappl_example/contract/",
    "answers_url": "https://YOUR_API_HOST/v1/client-intake-applications/ciappl_example/answers/"
  }
}
```

Save these identifiers before continuing. `invite_client: false` lets you populate the intake first. `true` sends a client Portal invitation during creation; omission or `null` inherits the source's invitation setting. To email a direct link to the intake form after adding answers, use the handoff in the completion guide below.

## 3. Complete and submit the intake

Continue with [Complete and submit a client intake](https://docs.staging.levr.ai/guides/client-intake-application.md), using the returned `client_intake_application` ID and URLs. That guide covers:

1. Reading the form's questions and saving or correcting answers.
2. Uploading supporting documents.
3. Emailing the client a link to finish, or checking readiness and submitting through the API.
4. Following submission and review through webhooks or polling.

The integration and shared client form use the same saved answers and files. In the receiving Portal, open **Businesses → Cedar Ridge Engineering Ltd. → Client intake** to review the same form.

**You've finished when** the intake contains the intended information and its status is `submitted`. Submission notifies the receiving team according to the Portal's notification settings and starts applicable intake preparation automation. Creating the business or saving answers does not trigger submission.

## If creation fails

| Response | Next action |
| --- | --- |
| `401`, `403`, or record not found | Check the environment, source ID, key permissions, and scope. |
| `409 source_channel_not_ready` | Ask the administrator to resolve the reported setup problem, then read the source again. |
| Validation error | Correct the named field against the business creation schema. |
| Connection failure | Retry the same endpoint, body, and idempotency key to recover the result. |

Save the business and application IDs as soon as creation succeeds. Resume that intake if a later answer write or submission fails; do not create another business.