Account Engagement Form Handlers: A Practical Guide to Lead Capture
A form handler lets your own website forms feed Marketing Cloud Account Engagement (formerly Pardot) without rebuilding them. This guide covers when to use one, how to set it up and map fields, how to post data safely, and the limits that cause lost leads.
Key Takeaways
- A form handler is an endpoint, not a form. You keep your own HTML or third-party form and point its post URL at the handler. Account Engagement creates or updates the prospect and runs your completion actions.
- Use a hosted form when you want progressive profiling, built-in bot protection and view and error reporting. Use a form handler when your form must keep its own design, stay in a third-party tool, or post to more than one system.
- Post from the browser. A browser post carries the visitor cookie, so page views before the submission join the prospect's history. A server-side post loses that link unless you rebuild it.
- Protect it yourself. Form handlers have no built-in CAPTCHA. Salesforce recommends bot protection and offers a honeypot field for external forms.
- Failures are silent. Account Engagement keeps no log of failed submissions, so test field names, required fields, encoding and redirects before launch.
An Account Engagement form handler connects a form you already own (a contact form on your website, a WordPress plugin form, or a form in another tool) to Marketing Cloud Account Engagement, the product many teams still call Pardot. Visitors keep seeing the form your web team designed. Behind it, each submission becomes a tracked prospect that can be scored, assigned and synced to Salesforce as a lead.
This guide is written for marketing operations and Salesforce teams at growing and mid-market companies. It replaces our earlier introduction with current navigation, the rules Salesforce documents for field mapping and posting, and the failure points that most setup guides leave out.
What Is an Account Engagement Form Handler?
An Account Engagement form handler is an endpoint URL that receives submissions from a form built outside Account Engagement. You map each field on your form to a prospect field, then set the form's post URL to the handler. Account Engagement records the submission, creates or updates the prospect, runs completion actions and redirects the visitor. It is available in every Account Engagement edition.
Salesforce positions form handlers as the alternative to its hosted forms. Account Engagement does not generate the form for you. It generates a URL, and your existing form keeps its own HTML, styling and scripts. Salesforce lists four reasons to choose one:
Full design control
The form looks and behaves exactly as your site's code defines it, with no hosted-form layout or styling to work around.
More than one database
The same submission can go to Account Engagement and to another system, such as Salesforce Web-to-Lead or your own application.
Existing forms stay
Forms that already work, and the lead flow behind them, keep running. You add tracking without a rebuild.
Third-party form tools
Forms built in a form builder or CMS plugin can post into Account Engagement, as long as the tool lets you set the post URL.
Source: Salesforce Help, Form Handlers.
Account Engagement Form vs Form Handler: Which Should You Use?
Use a hosted Account Engagement form when you can design the form inside Account Engagement and want its built-in features: progressive profiling, bot protection, view and error reporting, and thank-you content. Use a form handler when the form must stay on your own code or a third-party tool, or post to several systems. Both validate email addresses, prevent duplicates and trigger automation.
| Capability | Hosted form | Form handler |
|---|---|---|
| Prevents duplicate prospects | Yes | Yes |
| Validates email addresses | Yes | Yes |
| Autoresponder email, success redirect, automation rules on completion | Yes | Yes |
| Progressive profiling | Yes | No |
| Built-in bot protection | Yes | No |
| Form views and error data | Yes | No |
| Landing pages and thank-you content | Yes | No |
| Third-party forms and existing lead flow | No | Yes |
| Salesforce Web-to-Lead forms | No | Yes |
| Custom front-end code | No | Yes |
Source: Salesforce Help, Hosted Forms Versus Form Handlers.
A form handler fits when your web team owns the form code, the form lives in a CMS plugin or form builder, the same data must also reach Salesforce Web-to-Lead or another system, or you are adding Account Engagement to a site whose forms already work.
A hosted form is the better choice when you want progressive profiling, dependent fields, reCAPTCHA, or conversion reporting that includes views and errors, and nobody needs the form to live outside Account Engagement. A form handler cannot add any of these.
For hosted-form features, see our guide to dependent fields in Account Engagement forms.
What Happens When Someone Submits a Form Handler?
The browser posts the form fields to the handler URL. Account Engagement matches the submission to a prospect, using the visitor cookie first and the email address next, then creates or updates that prospect, runs completion actions, redirects the visitor and queues the prospect for sync to Salesforce. Each step has its own rules, and most problems trace back to one of them.
Your form posts to the handler endpoint
The form's action URL is the form handler URL. The input names must match the external field names you mapped. Submissions must be a standard POST, not Ajax and not multipart.
Account Engagement finds or creates the prospect
A cookied visitor updates their own prospect. Otherwise the email decides: one match is updated; several matches go to the prospect with the most recent activity; a match in the recycle bin is restored; no match creates a new prospect.
Completion actions, then the redirect
Lists, scores, assignments, notifications and autoresponders run, then the visitor goes to the success location, or to the error location when a required field is missing.
The prospect syncs to Salesforce
A form handler submission queues the prospect for sync, which runs every 2–4 minutes. Whether a new lead is created depends on assignment and your connector settings.
The matching rules above apply to accounts that allow multiple prospects with the same email address, which Salesforce has enabled by default for business units created since 14 June 2016. One consequence surprises teams: when a cookied prospect submits a new email address, Account Engagement creates an additional prospect rather than changing the email on the existing one. Sources: Considerations for Using Form Handlers and prospect syncing.
How Do You Set Up a Form Handler in Account Engagement?
In the Account Engagement Lightning app, open Content, then Form Handlers, and click Add Form Handler. Give it a name, folder and campaign, choose success and error locations, add completion actions and map every field on your form. Save it, copy the endpoint URL, and set that URL as your form's action. You need the Administrator or Marketing role.
| Setting | What to enter, and why it matters |
|---|---|
| Name and folder | Name the handler after the form and page it serves, for example "Website – Contact Us". Use the same folder structure as your other assets so reports stay readable. |
| Campaign | Required. Choose the campaign this handler's submissions should be credited to, so source reporting stays accurate. |
| Tracker domain | Use your branded tracker domain, so the endpoint sits on your own domain. Redirect overrides (Section 10) only work on your root tracker domain or go.pardot.com. |
| Data forwarding | Turn it on only when the submission must also be posted to the success location, such as Web-to-Lead or your own server. |
| Success location | "Referring URL" returns visitors to the page that held the form. "Specific URL" sends them to a thank-you page, or forwards the data on. |
| Error location | Usually the form page itself, so visitors can correct missing required fields. Error details arrive as URL parameters your page can display. |
| Kiosk / Data Entry Mode | Turn it on only for server-side posts or event sign-up stations. It stops the submitting browser being cookied as the prospect. |
| Completion actions | What happens after a successful submission: lists, scores, assignment, notifications and autoresponders. See Section 09. |
| Form fields | One mapping per input on your form. An email field is added automatically. See Section 05. |
Sources: Salesforce Help, Create a Form Handler; Account Engagement API, Form Handler object.
To connect your form, open the saved handler, choose View form handler code, copy the URL and paste it into your form's action attribute, or into the "post URL" or "webhook" setting of your form tool. In the classic Account Engagement interface the same screen is under Marketing, Forms, Form Handlers. Guides that send you to a "Pardot Settings" tab, or promise a generated HTML form, describe neither interface.
How Should You Map Form Handler Fields?
Map every input your form sends: the external field name must match the input's name attribute exactly, including case, and each one points to a prospect field. Mark a field required in the handler only if it is also required on the form, choose a data format that matches what visitors type, and keep the automatically added email field.
| Rule | What it means in practice |
|---|---|
| Names are case-sensitive | An input named Company does not match an external field name of company. The value is dropped without an error. |
| Email is always there | Every new form handler includes an email field. Salesforce recommends making email required on your form as well. |
| Required on both sides | If the handler requires a field and the form does not, a blank value sends the visitor to the error location and the submission is not recorded. |
| Data formats | Text, number, email, email with a valid mail server, or email not from ISPs and free email providers. The last two check the domain and mail server, and can block personal addresses. |
| Match the field type | A phone number such as (555) 010-0100 posted to a number-type field causes an error. Map phone numbers to text. |
| Custom fields | Map to the prospect custom field you created. Each field can carry its own error message, edited on the field's Advanced tab. |
| Keep first values | A field can keep its initial value on later submissions. Use it for first-touch details such as the original lead source. |
Sources: Create a Form Handler, Form Handler Field object, and the Salesforce knowledge article Troubleshoot form handlers.
Hidden fields are mapped the same way. They are the simplest way to pass UTM values, the page a form sits on, or a product interest that your page already knows, so routing and scoring can use them without asking the visitor.
Browser Post or Server-Side Post: Which Method Keeps Tracking Intact?
Post from the browser whenever you can. When the visitor's browser submits straight to the handler, Account Engagement reads its visitor cookie and joins the visitor's earlier page views to the prospect. When your server posts instead, the submission is recorded but the cookie is not, so that history is lost unless you take extra steps.
Browser post to the handler
RecommendedBest for: most website and plugin forms.
The form's action is the handler URL. Tracking, redirects and error handling all work as designed. If your site sets a strict referrer policy, add <meta name="referrer" content="no-referrer-when-downgrade" /> to the page head, because the handler relies on the referring URL.
Browser post with data forwarding
Two systemsBest for: forms whose data must also reach your own server or Web-to-Lead.
The browser still posts to the handler, which keeps the cookie. With data forwarding on, the handler passes the submission on to the success location, so your server or Salesforce receives the same fields.
Server post, then a hidden iframe
WorkaroundBest for: forms that must post to your server first.
Your server takes the submission, and the thank-you page loads the form handler in a hidden iframe with at least the email address. The iframe request comes from the visitor's browser, so the cookie is captured.
Server-side post only
Use with careBest for: back-end integrations with no browser involved.
Turn on Kiosk / Data Entry Mode, or your server is treated as the visitor. The prospect gets the submission but no tracking history. To reconnect it you have to capture and assign the visitor ID through the API, or wait for a later tracked email click. Salesforce Support treats this pattern as custom work.
Sources: Salesforce knowledge articles form handler posting methods and re-linking visitors after a server-side post.
Two posting styles do not work at all. Ajax submissions are not supported, because form handlers do not accept CORS or JSONP requests. And a form that sends multipart/form-data, the encoding used for file uploads, is rejected: leave the enctype empty or use application/x-www-form-urlencoded.
Can a Form Handler Work With Salesforce Web-to-Lead?
Yes. A form handler can sit in front of an existing Web-to-Lead form and forward each submission to Salesforce, so both systems receive it almost at the same time. Turn on data forwarding and set the Web-to-Lead post URL as the success location. Do not combine it with completion actions that assign prospects: Salesforce warns that this creates duplicate records.

- In the form handler, enable data forwarding to the success location.
- Set the success location to a specific URL: your Web-to-Lead post URL. In production it is typically
https://webto.salesforce.com/servlet/servlet.WebToLead?encoding=UTF-8. - Set the error location to the page that holds the form.
- On the form, change the action to the form handler URL and the Web-to-Lead return URL to your confirmation page.
- Map every Web-to-Lead input name in the handler, so Account Engagement receives the same values as Salesforce.
This pattern suits teams whose lead assignment rules already run on Web-to-Lead. If you want Account Engagement to own assignment instead, retire the Web-to-Lead post and let the connector create the lead (Section 09). Running both is how duplicate leads appear. Source: Integrate Account Engagement With Web-to-Lead.
How Do You Protect a Form Handler From Spam and Bots?
A form handler has no built-in CAPTCHA, so protection is your job. Add Account Engagement's honeypot field to the form, add a CAPTCHA or IP blocking in your form tool, and consider confirmed opt-in for list sign-ups. Salesforce warns that an unprotected form handler can make you complicit in subscription bombing, where bots sign real addresses up en masse.
- Honeypot field: add a hidden input named
pardot_extra_fieldinside a hidden container. People never see it; bots fill it in, and Account Engagement rejects any submission where it has a value. Source: Add a honeypot to external forms. - CAPTCHA in the form tool: reCAPTCHA and conditional CAPTCHA in Account Engagement apply to hosted forms only. For a form handler, the CAPTCHA has to run in your own form or plugin before the post.
- Confirmed opt-in: Salesforce documents a pattern where a second form handler serves as the confirmation link in an email and sets the opt-in field when clicked. Use a custom tracker domain for it.
- Email formats: the stricter email formats in Section 05 reject addresses with no working mail server.
How Do Completion Actions Route Form Handler Leads to Sales?
Completion actions run after each successful submission and decide what happens to the lead: which list it joins, how its score changes, who owns it and who is told. To create a Salesforce lead, assign the prospect to a user, queue or group, or use a Salesforce active assignment rule. The prospect then syncs, usually within minutes.
| Goal | Completion actions to use |
|---|---|
| Put the lead in front of sales | Assign via Salesforce active assignment rule, assign to user, assign to queue, or add to group; then notify assigned user. |
| Track the source | Add to Salesforce campaign, set first-touch or source campaign, or change a field value such as a lead source detail. |
| Qualify | Adjust score or adjust score for a scoring category, and set a profile for grading. |
| Follow up | Send an autoresponder email, create a Salesforce task, or notify a user, a Slack channel or via Twilio. |
| Nurture | Add to list (the entry point for an Engagement Studio program) or add tags. |
Source: Salesforce Help, Completion Action Definitions and Completion Action Considerations.
Four details decide whether this works as expected:
- Order is not guaranteed. Completion actions run in no defined order, so one action cannot rely on another having finished.
- Tasks wait for an owner. A "Create Salesforce task" action only syncs once the prospect is assigned. Add to Salesforce campaign only works once a lead or contact exists.
- Assignment does not reassign. Assign actions do not move a prospect who already has an owner.
- Limits apply. An asset can hold up to 15 completion actions and 6 conditional groups, and only future submissions are affected by a change.
For distribution logic beyond these actions, see our guides to Account Engagement automation rules and round-robin lead assignment.
Why Do Form Handler Submissions Fail?
Most failed submissions come from a field name that does not match, a required field left blank, a value in the wrong format, or a post method the handler does not accept. Account Engagement keeps no log of failed form handler submissions, so you will not find the evidence later. These are the causes Salesforce lists, and how to avoid each one.
success_location and error_location parameters override the saved locations for one post, but only when URL-encoded and on your root tracker domain or go.pardot.com. Otherwise the visitor returns to the referring page.Sources: Troubleshoot form handlers and Considerations for Using Form Handlers.
A quieter issue is throttling. On repeat submissions from the same prospect, Account Engagement throttles visitor activities and autoresponder emails. If every submission must send an email, such as a document request, turn on the handler's setting to disable visitor activity throttling.
A Form Handler Testing Checklist Before Go-Live
Because failures leave no log, test every form before it goes live, and again after any change to the page or the form plugin. Use a fresh browser session and an email address that does not exist as a prospect yet.
| Check | What a pass looks like |
|---|---|
| 1. Field names | Every input name on the live page matches an external field name, letter for letter. |
| 2. Happy path | A complete submission lands on the success page and creates a prospect with every field filled. |
| 3. Error path | Leaving a required field blank returns to the error location, and the page shows a readable message. |
| 4. Tracking | The new prospect's activity shows the page views made before the submission, which proves the cookie was linked. |
| 5. Completion actions | The list, score, assignment, notification and autoresponder all happened once. |
| 6. Salesforce | Within a few minutes, one lead (not two) exists with the right owner and campaign. |
| 7. Repeat submission | A second submission from the same browser updates the same prospect. |
| 8. Honeypot | A test post with pardot_extra_field filled in is rejected. |
How Do You Measure Form Handler Performance?
Account Engagement reports three numbers for each form handler: total submissions, unique submissions and conversions, where a conversion is an anonymous visitor who submitted and became a prospect. Find them under Account Engagement Reports, then Marketing Assets and Forms. Form handlers do not report views or errors, so measure conversion rate in your web analytics.
Single-handler reports also show when the handler was last submitted, which is a simple way to spot a broken form: a busy contact form with no submission for days usually means a field or plugin changed. Note that the summary table can show more conversions than the report page, because it still counts archived and deleted prospects. Source: Form Handler Table Metrics.
To judge pipeline impact rather than volume, report on the Salesforce campaign the handler assigns and on the leads it creates. If you use Data 360 (formerly Data Cloud), Salesforce maps Account Engagement form handler activity into its website engagement data as a form-handler-submit interaction, so form handler submissions can sit beside other engagement in segments and insights.
Form Handlers in Marketing Cloud Next
Marketing Cloud Next, Salesforce's newer marketing product, has its own form handlers. They do the same job of receiving submissions from an existing website form, but they work differently: each one triggers a Salesforce flow, generates a data source in Data 360, and is integrated server-side through the Connect API rather than by a browser post.
We found no Salesforce notice deprecating Account Engagement form handlers, and they remain the documented way to connect external forms to Account Engagement. If you are already planning a move to Marketing Cloud Next, inventory your form handlers early: field mappings, completion actions and posting methods all need a new design there. Sources: Trailhead, Explore lead generation methods, and the developer guide to form handlers.
How Twopir Consulting Helps With Account Engagement Lead Capture
Twopir Consulting is a Salesforce Partner and HubSpot Partner. We help growing and mid-market companies solve complex CRM, integration and business system challenges: we implement, rescue, optimize, and integrate complex CRM and revenue systems. For lead capture, that means tracing every form on your site to a prospect, an owner and a Salesforce lead, and fixing the points where leads drop out.
- New implementations: we design forms, form handlers, completion actions and connector settings together through our Account Engagement consulting.
- Inherited orgs: we audit form handlers that nobody remembers setting up, map their fields again and remove duplicate lead paths.
- Tracking foundations: form handler tracking depends on a working tracker domain and website tracking code. Our Pardot rebuild case study shows that work for an organization moving to a new Salesforce org.
- Platform choices: if you are weighing Account Engagement against Marketing Cloud Next, we map your forms and lead flow onto both.
Find Out Where Your Form Leads Go
On a 30-minute discovery call, a Twopir Account Engagement consultant will review how your website forms reach Account Engagement and Salesforce, and show you where leads are being lost or duplicated.
Schedule a Discovery CallThe Bottom Line
A form handler is the right tool when your forms need to stay your own. It gives Account Engagement every submission without a rebuild, but it hands you jobs a hosted form would do for you: bot protection, error display and testing. Set it up with exact field names, post from the browser, and let one system own lead assignment.
- 1
A form handler is an endpoint URL. Your form keeps its own code and posts to it.
- 2
Choose hosted forms for progressive profiling, bot protection and view reporting; choose form handlers for custom, third-party or multi-system forms.
- 3
External field names are case-sensitive, and required fields must match on both sides.
- 4
Browser posts keep visitor tracking. Server posts need Kiosk mode and extra work to relink it.
- 5
Add the honeypot field, assign in one place only, and test before every launch, because failed submissions leave no log.
Frequently Asked Questions
A form is built and hosted in Account Engagement, with progressive profiling, bot protection and view and error reporting. A form handler is an endpoint URL that receives submissions from a form you build elsewhere, such as your website code or a form plugin. Both create or update prospects and can trigger completion actions.
Open the form handler in Account Engagement and choose View form handler code, or copy the endpoint URL from its summary. Set that URL as your form's action attribute, or as the post URL in your form tool. Account Engagement does not generate an HTML form for a form handler.
Yes, when the visitor's browser posts directly to the handler. Account Engagement then links the visitor cookie, so earlier page views join the prospect's history. A server-side post records the submission but not the cookie, and should use Kiosk / Data Entry Mode.
Not through Account Engagement. Its reCAPTCHA and conditional CAPTCHA apply to hosted forms only. For a form handler, add a CAPTCHA in your own form or plugin, add the pardot_extra_field honeypot field, and consider confirmed opt-in. Salesforce recommends bot protection for every form handler.
Yes. Enable data forwarding on the form handler and set your Web-to-Lead post URL as the success location, so both systems receive the submission. Avoid completion actions that assign prospects in this setup, because Salesforce warns that it creates duplicate records.
The usual causes are input names that do not match the case-sensitive external field names, a required field left blank, a value in the wrong format, an Ajax or multipart/form-data post, or a stripped referrer. Account Engagement keeps no log of failed submissions, so test each form directly.
Indirectly. A submission creates or updates the prospect and queues it for sync, which runs every 2 to 4 minutes. A new Salesforce lead is created when the prospect is assigned to a user, queue or group, or through an active assignment rule, depending on your connector settings.
Twopir Consulting
Twopir Consulting works with growing, mid-market, and enterprise organizations that need help with complex CRM implementations, integrations, and business system challenges. We implement, rescue, optimize, and integrate complex CRM and revenue systems on Salesforce and HubSpot, for clients across the US, UK, Australia and New Zealand, the UAE and Canada.