# Businesses

Add businesses through a Lead source, complete their intake applications, and follow their progress.

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

Authentication: Bearer — Portal API key

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

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

## Create a business in the receiving Portal

A business is the company seeking funding. Client intake optionally collects information and documents; funding work can start before intake exists.

For a step-by-step example, choose the starting experience configured for your source:

- [Business profile](https://docs.staging.levr.ai/guides/source-business.md): send business and contact details to the receiving Portal.
- [Client intake](https://docs.staging.levr.ai/guides/source-client-intake.md): create the business and fill in its intake form.
- [Deal application](https://docs.staging.levr.ai/guides/source-direct-deal.md): create the business and start an application to the receiving organisation.
- [Funding and matchmaking](https://docs.staging.levr.ai/guides/source-matchmaking.md): create the business, start a funding request, and find funding options.

1. Use the source ID supplied in API setup. A source-scoped key can also find its selected IDs in `GET /v1/` → `api_key.target_slugs`.
2. Read `GET /v1/source-channels/{source_channel_id}/` to confirm its starting experience and readiness.
3. Send `POST /v1/businesses/` with `source_channel_id`, the `business` contact details, and a retained `Idempotency-Key`. The source determines which empty application is initialized; creation does not accept application answers.
4. Save the receipt. If it includes `client_intake_application` or `deal_application`, follow that object's `contract_url` and `answers_url` to populate the form. Answer writes require their own permission, idempotency key, and the current answer ETag as `If-Match`.

Use the live application contract's exact `block_key` and `field_key` values. Documents and repeated items use the operations in that contract. Business creation, answer updates, and application submission are separate commands; save progress and retry only the failed command.

`invite_client` omitted or null follows the source's invitation default. `false` suppresses the invitation; `true` sends it during creation, before later answers are saved. To populate a form before inviting the client, use false and arrange the invitation through the receiving team's Portal afterward. A returned `invitation_url` is a private client-access link, not a logging field.

The `lead_submissions:write` permission permits creation and source setup reads. Application reads/writes and Business reads require their own permissions; returned IDs do not grant access. Use the current creation schema rather than assuming fields such as `owners` or `legal_name` exist.

Provider-scoped administrative keys may list sources with `source_channels:read`, or create/remove them with `source_channels:write`.
These are not prerequisites for a developer already given a source slug. To remove an unused source, send
`DELETE /v1/source-channels/{source_channel_id}/` with `Idempotency-Key` and no body. Attributed Businesses/Deals prevent removal (`409`).
Removal revokes the source's dedicated default key and legacy credential, preserving history and unrelated keys.
Retry with the same administrative API key and the same `Idempotency-Key` to replay the original response.

## Manage contacts

Business contacts are a complete replacement set. Use people reachable within the key’s selected targets. `new_people` can create and attach initial contacts under Business Write; this does not grant global People edits. Existing email matches must already be in scope and their CRM fields are not overwritten. A `primary_person_id` must also appear in `person_ids`; null clears the primary designation. An empty set clears the contacts. Read the current set and its ETag before replacing it, then read back the result.

## Collect information after creating a business

For an existing source-owned business with no intake, call
`POST /v1/businesses/{business_id}/client-intake/` with no request body and a caller-generated
`Idempotency-Key`. Requires `businesses:write` OR `client_intake_applications:write`. The effective published source
intake template is used even when automatic intake is off. The response contains
`business_id`, `application_id`, `created`, and `frontend_link`: `201` for creation,
`200` when returning existing intake. An exact retry replays the original response.
This preserves business metadata and projects and sends no invitation.

In MCP, use `businesses.create_client_intake` with `provider_slug`, `business_id`,
and a UUID `idempotency_key`. Review the resulting intake, then share it separately.
The API share endpoint requires `client_intake_sharing:write`; internal AI
sharing uses the existing approval flow. An intake share grants application access,
not workspace membership. Existing project matching answers are not automatically
synchronized when intake is submitted; use the intake evidence in that project's autofill workflow.

## Save researched leads through MCP

`businesses.create` accepts the existing `provider_slug`, `name`, and `client_request_id`, plus optional
`contacts` (at most ten) and `initial_note` (private rich text, at most 20000 characters). Each contact needs an
`email` or `phone_number`; `full_name` and `job_title` are optional. Use only sourced details and do not invent
an owner's name for a generic business inbox. Existing contacts with the same normalized email are linked
without overwriting their information; new contacts are saved in the same Portal.

For researched leads, create People records only when a sourced person's name or an email is available.
A named person's phone-only contact is valid. General business phone numbers and contact-page URLs belong
in research notes or appropriate intake fields; a business name is not a person's identity.

The Business, contacts, links, and initial note commit together or all roll back. Retry identical arguments with
the same `client_request_id`; changed content requires a new request ID. Name-only creation remains supported.
Read the Business's people and notes after saving to verify the complete result. Check existing Businesses,
including archived records, before creating a researched lead; creation does not deduplicate company identities.

Research notes should preserve sources, relevance, important unknowns, and any requested outreach drafts.
Saving a Business does not send outreach, invite a client, share applications, or create a funding Project.
Normal workspace creation configuration, history, and integration events still apply. Archive unwanted leads
through the Portal to hide them from current work while preserving their history; archiving is not deletion.

### Include client intake during Business creation

Set `include_client_intake=true` on `businesses.create` to create or reuse intake using the source's effective
published template, even when automatic intake is off. The argument defaults to `false`, which retains normal
source behavior. This explicit request does not change source settings, share the application, or send invitations.

When requested, `client_intake_creation.status` is `created`, `existing`, or `unavailable`. The returned
`client_intake_application.id` identifies an available intake. If setup is unavailable, the Business, People, and
research note remain saved; `code` and `message` explain the missing setup. An identical retry returns the original
receipt. After correcting setup, call `businesses.create_client_intake` on that saved Business rather than create
another Business. Unexpected save failures still roll back the operation.

Creation does not populate intake answers. Read `client_intake_applications.get_contract` and `get_answers`, then
use `update_answers` with the latest `expected_answers_revision` to fill sourced facts that accurately match the
questions. Preserve existing answers and uncertainty; keep private assessments and outreach drafts in notes.
For larger evidence sets, prepare and review Autofill suggestions. Verify saved answers before reporting readiness.
AI-created intake uses the existing AI history attribution. Sharing requires a separate authorized action.


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

- [List Lead sources available for API business submissions](https://docs.staging.levr.ai/rest-api-reference/businesses/list-business-source-channels.md): `GET /source-channels/`

- [Create a business](https://docs.staging.levr.ai/rest-api-reference/businesses/create-business.md): `POST /businesses/`

- [Create a Lead source for API business submissions](https://docs.staging.levr.ai/rest-api-reference/businesses/create-business-source-channel.md): `POST /source-channels/`

- [Create client intake](https://docs.staging.levr.ai/rest-api-reference/businesses/create-business-client-intake.md): `POST /businesses/{business_id}/client-intake/`

- [Get a business and its portal status](https://docs.staging.levr.ai/rest-api-reference/businesses/get-business-status.md): `GET /businesses/{business_id}/`

- [Get client matchmaking settings](https://docs.staging.levr.ai/rest-api-reference/businesses/get-business-client-matchmaking.md): `GET /businesses/{business_id}/client-matchmaking/`

- [Get Lead source settings](https://docs.staging.levr.ai/rest-api-reference/businesses/get-source-channel.md): `GET /source-channels/{source_channel_id}/`

- [List a business's related project and deal references](https://docs.staging.levr.ai/rest-api-reference/businesses/get-business-activation.md): `GET /businesses/{business_id}/activation/`

- [List Business contacts](https://docs.staging.levr.ai/rest-api-reference/businesses/list-business-people.md): `GET /businesses/{business_id}/people/`

- [Replace Business contacts](https://docs.staging.levr.ai/rest-api-reference/businesses/replace-business-people.md): `PUT /businesses/{business_id}/people/`

- [Update a Business](https://docs.staging.levr.ai/rest-api-reference/businesses/update-business.md): `PATCH /businesses/{business_id}/`

- [Update client matchmaking settings](https://docs.staging.levr.ai/rest-api-reference/businesses/update-business-client-matchmaking.md): `PATCH /businesses/{business_id}/client-matchmaking/`

- [Move one Business to a workflow stage](https://docs.staging.levr.ai/rest-api-reference/businesses/move-business-stage.md): `PATCH /businesses/{business_id}/stage/`

- [Remove an unused API Lead source](https://docs.staging.levr.ai/rest-api-reference/businesses/remove-business-source-channel.md): `DELETE /source-channels/{source_channel_id}/`