REST API reference

Businesses

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

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: send business and contact details to the receiving Portal.
Client intake: create the business and fill in its intake form.
Deal application: create the business and start an application to the receiving organisation.
Funding and matchmaking: create the business, start a funding request, and find funding options.

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.
Read GET /v1/source-channels/{source_channel_id}/ to confirm its starting experience and readiness.
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.
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.

Available operations

Copy instructions to your AI agent

Request an integration