Updating Leads via Forms

By default, every form submission creates a new lead. But sometimes you want to update an existing lead instead: for example, when you send a re-engagement email asking a contact to update their information, or when you want to enrich lead data through a follow-up form.

Leadflip supports this by passing a lead identifier through the form URL. When the form is submitted, the system recognizes the lead and updates it instead of creating a duplicate.

How It Works

1. You include a lead token or lead ID as a URL parameter on the page where your form is embedded.
2. The form embed script detects the parameter and includes it in the submission.
3. The backend matches the identifier to an existing lead and updates its data with the submitted field values.
4. A timeline event is logged on the lead ("Lead updated via form submission").

If the identifier is invalid or the lead is not found, a new lead is created as usual; no errors are shown to the user.

Two Ways to Identify a Lead

Signed Token (Recommended)

The signed token (lf_token) is an encrypted, tamper-proof token that contains the lead ID. It cannot be guessed or modified by the end user. Use this when you control the link, for example in campaign emails or automation emails sent through Leadflip.

URL format:

https://yoursite.com/form-page?lf_token={{ lead.signed_token }}

The {{ lead.signed_token }} variable is available in the variable picker of every Email and Webhook action in automations, campaigns, and distribution templates.

Raw Lead ID (Flexible)

The raw lead ID (lf_lead_id) passes the lead's UUID directly in the URL. Use this when you work with external tools or build URLs manually, for example from a third-party email platform or a custom integration.

URL format:

https://yoursite.com/form-page?lf_lead_id=550e8400-e29b-41d4-a716-446655440000

You can find a lead's ID in the CRM (lead detail drawer) or via the API. The {{ lead.id }} variable is also available in the variable picker.

Setting Up a Lead Update Flow

Step 1: Create the Form

Build a form in the Form Builder as usual. The form should contain the fields you want the lead to update. There is no special setting needed; any form can handle both new leads and updates.

Step 2: Embed the Form on a Page

Embed the form on your website or landing page using the script tag. See Embedding & Sharing for details.

Step 3: Include the Token in Your Link

When sending an email (via campaigns, automations, or distribution), include the lead token in the link to your form page:

In a Campaign or Automation Email:

<a href="https://yoursite.com/update-form?lf_token={{ lead.signed_token }}">
  Update your information
</a>

In an external tool (using the raw ID):

https://yoursite.com/update-form?lf_lead_id=LEAD_UUID_HERE

Step 4: The Lead Submits the Form

When the lead clicks the link and submits the form, their existing data is updated with the new values. Only the fields present in the form are updated; other fields on the lead remain unchanged.

What Happens on Update vs. Create

Security

• Signed tokens are encrypted with your application's secret key. They cannot be forged or tampered with.
• Raw UUIDs are validated against the form's account and entity. A UUID from a different account or entity will not match; a new lead is created instead.
• Both methods verify that the lead belongs to the same account and same entity as the form before allowing an update.

Use Cases

• Re-engagement campaigns. Send a campaign email asking leads to update their contact details or preferences.
• Profile update forms. Provide a link in your app or portal where users can update their information.
• Lead enrichment. Send a follow-up form to collect additional data (e.g., company size, budget) after initial lead capture.
• Survey follow-ups. Attach survey responses to existing leads rather than creating duplicates.

Best Practices

• Use signed tokens when possible; they are more secure and prevent unauthorized updates.
• Use raw UUIDs only when integrating with external tools that cannot generate signed tokens.
• Test the flow. Submit a test form with a token and verify the lead was updated (not duplicated) in the CRM.
• Combine with pre-fill. You can use both update tokens and URL pre-fill parameters on the same form to pre-populate field values for the user.

Next Steps

• Learn about embedding forms
• Use variables in automation emails
• Form Builder overview