# Create a funding request and find matches

Create a business in the receiving Portal, open a linked funding request, and supply Criteria to find funding options. An internal integration or an external referrer can perform these steps with the required API permissions and source access.

**The result:** this flow creates a business, a Project linked to a client-visible funding request, and a matching run. Matching does not submit lender applications or guarantee a suitable match.

A **Project** is the receiving team's workspace for a funding goal. Its linked **funding request** is the client's view of that goal. Both use the same matching answers, called **Criteria**.

The source initializes client matchmaking access on the business relationship. Creating the business alone does not create the funding request or populate Criteria; those are separate steps below. For an existing business from another starting experience, [enable client matchmaking through the API](https://docs.staging.levr.ai/guides/source-business.md#enable-the-clients-matchmaking-experience), then continue at step 4. [Compare starting experiences](https://docs.staging.levr.ai/guides/index.md).

## 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 **Clients start with self-serve matchmaking**, 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`, `projects:write`, `project_criteria:write`, and `project_matching:write`.
- Confirmation that the source is ready and the Portal has a default business pipeline and stage. Client matchmaking, funding-request creation, and the receiving team’s matchmaking tools must be available. Published recipient Criteria must be available for matching. The receiving Portal must remain the business’s source owner with a live client relationship.

<details>
<summary>Configure the source if you have Portal access</summary>

With permission to manage the source, open the Lead source, then **Overview → Getting started → Change setup**, and choose **Clients start with self-serve matchmaking**. For a new source, choose **API integration** when creating it. Confirm the matchmaking and funding-request capabilities listed above with the Portal administrator.

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).

</details>

<details>
<summary>Create the source through the API instead</summary>

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":"matchmaking"}
```

`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`.

</details>

## 2. Check the source setup

Use your environment's API origin and a server-side bearer key; [Get started](https://docs.staging.levr.ai/rest-api.md) explains authentication. All requests below include `Authorization: Bearer <API_KEY>`. JSON writes also include `Content-Type: application/json` and a unique `Idempotency-Key`. Retain each write's key and body for retries.

Examples use illustrative IDs. Responses show only the fields needed for the next step; use the actual IDs and URLs returned by your API.

**Request**

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

**Response · selected fields**

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

Confirm `starting_experience` is `matchmaking` and `readiness.is_ready` is `true`. If the setup differs, confirm the source with the receiving Portal's administrator before creating records.

## 3. Create the business

Business creation uses the same payload structure for every starting experience. Send the source ID and contact details:

```http
POST /v1/businesses/
Idempotency-Key: website-lead-12345-business
```

```json
{
  "source_channel_id": "srcch_REPLACE_ME",
  "business": {
    "name": "Cedar Ridge Engineering Ltd.",
    "primary_contact_name": "Maya Chen",
    "primary_contact_email": "maya@example.com",
    "primary_contact_phone": "+16045550123"
  },
  "invite_client": false
}
```

`invite_client: false` suppresses the invitation. `true` sends it during creation, before subsequent answers are saved; omission or `null` follows the source's invitation setting. To save Criteria before inviting, keep it false and arrange the invitation through the receiving team's Portal afterward.

**Response · 201, selected fields**

```json
{
  "business": {
    "id": "biz_example",
    "url": "https://YOUR_API_HOST/v1/businesses/biz_example/"
  },
  "starting_experience": "matchmaking",
  "client_intake_application": null,
  "deal": null,
  "deal_application": null
}
```

Save `business.id` before continuing. An identical retry returns the original result; a new key can create another business. Application answers belong in later requests. If returned, `invitation_url` is a private client access link.

## 4. Create the linked funding request

Create a project for this funding goal. `create_funding_request: true` also creates a linked funding request in the client's Portal (called a service request in API fields). To run matching only in your Portal, omit this field; client matchmaking access is not required for a private Project.

**Request**

```http
POST /v1/projects/
Idempotency-Key: website-lead-12345-equipment-project
```

```json
{
  "business_id": "biz_example",
  "name": "Equipment expansion",
  "target_amount": "250000",
  "target_currency": "CAD",
  "create_funding_request": true
}
```

**Response · selected fields**

```json
{
  "id": "proj_example",
  "service_request_id": "srq_example",
  "contract_url": "https://YOUR_API_HOST/v1/projects/proj_example/matchmaking-application/contract/",
  "answers_url": "https://YOUR_API_HOST/v1/projects/proj_example/matchmaking-application/answers/"
}
```

Save both IDs. The Project and funding request share Criteria and matching work. Creation sends no invitation and does not expose private Project notes.

Already have a project? [Add its client funding request](https://docs.staging.levr.ai/guides/source-business.md#enable-the-clients-matchmaking-experience) rather than creating a second Project.

Already have a funding request for this goal? With `businesses:read`, [discover it through business activation](https://docs.staging.levr.ai/rest-api-reference/businesses/get-business-activation.md), then create the Project using only `business_id` and `service_request_id` to link that existing request.

## 5. Complete Criteria and find matches

Continue with [Find funding recommendations](https://docs.staging.levr.ai/guides/matchmaking.md), using `proj_example` as your Project ID. That walkthrough covers:

1. Reading the Project's questions and saving Criteria.
2. Attaching supporting documents.
3. Starting matching and polling for results or receiving a webhook.
4. Reviewing results, saving a shortlist, and creating a Deal for a selected recipient.
5. Continuing to the shared Deal guide to complete and submit its application.

You need `deals:write` to create Deals after matching, and `deal_applications:write` to complete and submit their applications. Saving a shortlist alone does not create or submit a Deal.

In the receiving Portal, open **Projects → Equipment expansion** to review Criteria and results. A client with access can continue the linked funding request. This example left invitations off; arrange any client invitation through the receiving team.

**You've finished when** the linked Project and funding request exist and you have completed the matching or Deal workflow required by your integration.

## 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. |
| `412` on an answer write | Read the latest answers, reconcile concurrent edits, and use their new ETag. |
| `409` on a retry | Check whether the body or precondition changed. Reuse a key only for the identical command. |
| Validation error | Correct the named field against the creation schema or the application's live contract. |

After a connection failure, retry the same endpoint with the same key and body; the operation may already have succeeded. Save progress after each step so an answer-write failure never causes another business to be created.