Lead Forms and CRM Handoff

1) The problem this lesson solves

A “form submitted successfully” message does not prove the intended lead reached the CRM correctly. A property can be renamed, a type can drift, consent context can disappear, or a retry can create a duplicate.

2) Lesson boundary

The owned artifact is Lead-to-CRM Handoff Contract v1. This lesson does not own the preceding plan configurator or the following website audit, and it performs no live CRM mutation.

3) Fact: a property is more than a label

HubSpot CRM property metadata includes fields such as name, label, type, fieldType, options and formField. An integration should use the governed internal property contract rather than display labels as stable keys.

4) Fact: form lifecycle has multiple states

HubSpot documentation separates callbacks before submission from onFormSubmitted after persistence and also documents server-side submission errors. A click or pre-submit event is not the same as persisted submission evidence.

5) Inference: form persistence is still not CRM reconciliation

Even after a form submission persists, you still need evidence that fields mapped to the intended CRM properties, normalization was valid and the intended record was created or updated.

6) Design: preserve submission identity

submission_id remains traceable from first handoff through retries and reconciliation. A retry must not erase the identity or outcome ambiguity of the earlier attempt.

7) Do not reconstruct source intent from CRM labels

Capture source_page_id and source_intent at the web edge. Do not later infer original intent from lifecycle stage, campaign labels or CRM presentation fields.

8) Make field-to-property mapping explicit

Each web field maps to a specific current CRM property with type and allowed options. Rename or schema drift should stop the handoff instead of silently dropping data.

9) Validation and normalization are different

type_validation asks whether payload data matches the destination contract. normalization_result records what the actual transformation produced. Keep the rule and the result separately auditable.

10) Carry consent context with the handoff

Consent cannot be inferred from submission success or the existence of a CRM record. Preserve the context supplied with that specific submission as separate evidence.

11) A timeout can hide a successful write

The CRM may create a record before the client sees a timeout. Blindly retrying CREATE can duplicate the lead; dedupe/idempotency plus lookup/reconciliation is required.

12) Core Evidence Contract

The artifact has 20 dimensions, 15 critical. The compact table below shows the baseline while JSON/CSV retains the complete mapping contract.

13) Browser success is not the CRM response

crm_response_ref is downstream evidence. A success message or browser callback is only a lifecycle signal and cannot fabricate record correctness.

14) SYNCED is an evidence-backed state

The handoff reaches SYNCED only when mapping, validation, consent, dedupe, operation, response and reconciliation evidence are sufficient. Otherwise preserve RETRY, MANUAL_REVIEW, HOLD or BLOCKED states.

15) Lab and transfer

The lab has eight fixtures and 48 assertions. In transfer, a new property becomes required, an enumeration gains allowed values and a retry arrives after a hidden successful write. Recompute mapping and dedupe from changed evidence instead of copying the baseline.