Business guides

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

Find the setup in the Portal

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.

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.

GET /v1/source-channels/srcch_example/

Response — relevant fields

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

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

201 Created — relevant fields

{
  "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, using the returned client_intake_application ID and URLs. That guide covers:

Reading the form's questions and saving or correcting answers.
Uploading supporting documents.
Emailing the client a link to finish, or checking readiness and submitting through the API.
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.

Copy instructions to your AI agent

Request an integration