# Create a business profile

Create a business and its primary contact in the receiving Portal through the API. Use this flow to transfer business records from an internal system or an external referrer's integration.

**The result:** the request creates a business profile with contact details. It does not start an intake form, Deal application, or funding request. The example suppresses client invitations.

This is the baseline for every starting experience. Add intake, a Deal, or matchmaking when needed using the follow-up calls below; you do not need to move the business to a different source.

## 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 **Business profile only**, 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 `businesses:read`.
- Confirmation that the source is ready and the Portal has a default business pipeline and stage. No published application is needed.

<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 **Business profile only**. For a new source, choose **API integration** when creating it.

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`. Use the returned `id` as `source_channel_id` when creating the business. Read `GET /v1/source-channels/{id}/` to confirm the source’s current setup and readiness.

```json
{
  "name": "Website enquiries",
  "starting_experience": "business_profile"
}
```

`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": "business_profile",
  "readiness": { "is_ready": true }
}
```

Confirm `starting_experience` is `business_profile` 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
}
```

An existing email address can reuse a contact within your key’s permitted scope. Creating a business does not overwrite that contact’s saved details.

`invite_client: false` suppresses the invitation. `true` sends it during creation; omission or `null` follows the source's invitation setting. To invite later, 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": "business_profile",
  "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. Verify the created business

The response's `business.id` identifies the new record; `business.url` is its **API** URL, not a Portal link. `client_intake_application` and `deal_application` are null; no Deal is created by this flow.

Read the returned `business.url` to confirm the saved record:

```http
GET /v1/businesses/biz_example/
```

If you have access to the receiving Portal, open **Businesses**, find **Cedar Ridge Engineering Ltd.**, and check the business and primary contact details. It should be in the receiving Portal’s default business pipeline and stage. Without Portal access, ask the receiving team to confirm the contact details.

**You've finished when** the saved business has the intended contact details and no unexpected invitation was sent. The receiving team can now work with the business record.

## Continue from the baseline

The source records where the business came from and chooses what is created alongside it. You can add other applications and funding goals later. Each action requires the relevant API permissions, access to the business, and any Portal features listed below.

### Add client intake

With `client_intake_applications:write`, create the intake with no request body:

```http
POST /v1/businesses/biz_example/client-intake/
Idempotency-Key: website-lead-12345-intake
```

**Response · selected fields**

```json
{
  "business_id": "biz_example",
  "application_id": "ciappl_example",
  "created": true,
  "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/"
  }
}
```

This uses the source's published intake template. Automatic intake creation can remain disabled; the business must have originated through the receiving Portal. If intake already exists, the endpoint returns it with `created: false` instead of creating another form.

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. Complete and submit this intake in the same way as one created automatically with the business.

### Start a Deal application

With `deal_recipients:read`, read the available recipients:

```http
GET /v1/deal-recipients/?business_id=biz_example
```

Choose the receiving Portal's recipient with `can_create_deal: true` to start an application to that Portal. With `deals:write`, use its returned ID:

```http
POST /v1/deals/
Idempotency-Key: website-lead-12345-deal
```

```json
{
  "business_id": "biz_example",
  "recipient_id": "<recipient-id-from-discovery>"
}
```

**Response · selected fields**

```json
{
  "id": "deal_example",
  "application": { "id": "dapp_example" }
}
```

When applying to the receiving Portal, the Deal uses the source's configured application, or the Portal's default published application if none is configured. This is the same form you would get from the Deal application starting experience.

Continue with [Complete and submit a Deal](https://docs.staging.levr.ai/guides/deal-application.md), using `application.id` and `deal_applications:write`. Recipient discovery also lets you choose another available recipient when the business is ready to apply elsewhere.

### Create a project

With `projects:write`, create a project to track a funding goal:

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

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

Save the returned Project `id`. You can [complete Criteria and find funding recommendations](https://docs.staging.levr.ai/guides/matchmaking.md) with the permissions and Portal setup listed in that guide. Client matchmaking does not need to be enabled to run matching for your team.

### Enable the client's matchmaking experience

Let the client use matchmaking, just as a self-serve matchmaking source would do during business creation. With `businesses:read`, read the current setting and retain its ETag:

```http
GET /v1/businesses/biz_example/client-matchmaking/
```

**Response · selected fields**

```json
{
  "business_id": "biz_example",
  "enabled": false,
  "available": false,
  "revision": "<current-revision>"
}
```

`enabled` records whether you have allowed client matchmaking for this business. `available` tells you whether the client can use it; the Portal must also support client matchmaking. With `businesses:write`, enable it using the returned ETag:

```http
PATCH /v1/businesses/biz_example/client-matchmaking/
If-Match: "<current-revision>"
Idempotency-Key: website-lead-12345-client-matchmaking
```

```json
{ "enabled": true }
```

This allows client matchmaking for the business. It does not create a project or funding request, or send an invitation. The business must have an active, approved relationship with the receiving Portal. On `412`, read the setting again and confirm your intended change before retrying.

To include the client in a funding goal, [create a Project with a linked funding request](https://docs.staging.levr.ai/guides/source-matchmaking.md#4-create-the-linked-funding-request). If you already created the project above, add its funding request without duplicating the Project:

```http
GET /v1/projects/proj_example/
```

Use the Project response's ETag for the next request. No request body is needed:

```http
POST /v1/projects/proj_example/funding-request/
If-Match: "<project-revision>"
Idempotency-Key: website-lead-12345-project-funding-request
```

The returned Project includes its linked `service_request_id`: `201` means the request was created, and `200` means the Project already had one. The client and your team use the same Criteria and matching work; private Project notes remain private. This requires `projects:write`, enabled client matchmaking, an active relationship with the Portal where the business originated, and the Portal's funding-request capability. It sends no invitation.

## 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 | Check whether the body or precondition changed. Reuse a key only for the identical command. |
| Validation error | Correct the named business or contact field against the creation schema. |

After a connection failure, retry the same endpoint with the same key and body; the operation may already have succeeded. Keep the returned business ID so later work continues on the same business.