Business guides

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. Compare starting experiences.

Already have a business from a Business profile only source? Add this setup to the existing business, 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.

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.

{"name":"Website enquiries","starting_experience":"deal_application"}

starting_experience is required when creating a source. To find an existing source, use List Lead sources with source_channels:read.

2. Check the source setup

Every request uses Authorization: Bearer <api-key>. Keep the key on your server; Get started shows this environment's API address. The examples use illustrative IDs and abbreviated responses.

GET /v1/source-channels/srcch_example/

Response excerpt · 200:

{
  "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.

POST /v1/businesses/
Content-Type: application/json
Idempotency-Key: website-lead-12345-business

{
  "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:

{
  "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, 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.

Copy instructions to your AI agent

Request an integration