Form to CRM

Org admins can read and set a mapping with GET/PUT /v1/orgs/{orgId}/crm/forms/{formId}/mapping or MCP form_crm_mapping_get and form_crm_mapping_set. The caller needs access to the form (including its project), org:manage_forms, crm:create and crm:edit; pipeline configuration also requires crm:manage_pipelines, lifecycle configuration crm:manage_lifecycles. CRM keys need the crm resource family and crm.api.enabled.

crm.formMapping is on by default on every plan; an org override of false hides the management routes/tools and pauses queued deliveries without spending their retry budget. forms.enabled, crm.enabled and crm.v2.records must also be on. Every mapping starts disabled: configuring it without enabled:true creates no CRM intent. No settings or existing forms are activated during deployment.

The mapping contains kind:crm_record, recordKind:person|company, and fields mapping CRM attributes to form field keys. People support firstName, lastName, primaryEmail (an email field), primaryPhone, title, notes and externalKey. Companies support name, domain, website, industry, phone, notes and externalKey. Upsert identity is externalKey or normalized email for people, externalKey or normalized domain for companies. Existing identities cannot be replaced by an anonymous submission. Company names are required. Missing submitted identity is a visible terminal delivery failure; the canonical response remains stored.

tags (existing tag IDs) and flags (existing flag keys) are additive. pipeline:{pipelineId,stageId} reuses the oldest unarchived deal for the same lead and pipeline, or creates one at that live, org-owned stage when absent. A repeat inquiry never resets an existing deal’s stage, outcome or value. lifecycle:{key,stage?} enrols into a published, applicable lifecycle and preserves an existing active enrolment; it never bypasses applicability rules.

consentFieldKey can refer only to a multi_select checkbox with explicit consent:{purpose,basis:express,disclosure,optionValue} metadata and a matching option. Only the checked, visible option records evidence. The signed access ticket binds the displayed definition; edits before submission require a reload. The definition and mapping are captured when the response is submitted, so later edits cannot invent consent. Evidence lives in the linked activity and transaction audit; this feature does not grant outreach eligibility, change CASL status, lift a suppression, or clear doNotContact.

Complete submissions capture the mapping and definition in the existing durable delivery outbox. Partial submissions produce no CRM intent. Worker delivery is idempotent by the canonical response ID and destination: CRM upsert, deal/enrolment, linked form_response activity, audit and successful delivery receipt commit together. Failed CRM delivery does not lose the submitted form. Existing form limits, signed tickets, bot checks, HTTP rate limits, bounded field/taxonomy sizes, and bounded worker batches apply; retries retain the existing delivery limit. A disabled mapping pauses pending CRM work until re-enabled.

Example PUT body:

{"mapping":{"kind":"crm_record","recordKind":"person","fields":{"primaryEmail":"email","firstName":"first"},"tags":[],"flags":[]},"enabled":true}

• API reference: GET /v1/openapi.json.
• MCP tools: MCP tools.
• Runbook: delivery and configuration.

Web: Forms > the form > Data > CRM lead destination. Map fields, choose an optional opportunity pipeline and initial stage, and explicitly enable delivery. Build > Multi select > Optional consent evidence defines the purpose, exact disclosure and opt-in option. A new mapping starts disabled. CRM records and opportunities first created by a form use the existing api source; updates preserve the original source. No new entitlement is introduced.

Public /f/<token> pages can be embedded in an HTTP or HTTPS website. The Access tab shows iframe code when a public link is minted. Invite links, login and organization pages keep their existing same-origin frame policy; public access still rejects member-only and verified-email audiences.