WPForms documents a specific URL key format for Prefill by URL: wpf followed by the form ID, field ID, and optional subfield. A query such as contact-reason=sales may look readable but will not populate the field unless custom code maps it. Failures also come from outdated IDs after duplication, wrong choice values, missing URL encoding, cached form markup, redirects that drop the query, dynamic choices, and subfield names that do not match the field configuration.
Use this when a WPForms text, dropdown, address, name, checkbox, or dynamic-choice field stays empty or selects the wrong value after opening a URL with query parameters.
Quick answer
Enable Prefill by URL for the form, confirm the current form and field IDs, and build the key in the documented wpf{formID}_{fieldID}_{subfield} shape. Encode spaces and special characters. For dropdowns and choices, test whether the field expects the visible label or stored value. Follow redirects and inspect the final URL, then compare uncached and cached form markup. Treat marketing attribution storage as a separate requirement because native prefilling only moves a value from the current URL into a field.
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| Text | wpf20_1=Sales | Field and entry show Sales |
| Address | Optional subfield key | Correct component fills |
| Choice | Label versus stored value | Expected option selected |
| Redirect | Final URL retains key | Public form fills |
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence | Verification |
|---|
| Inventory current IDs and field contracts | Record the live form ID, field ID, field type, subfield name, show-values setting, dynamic choices, conditional logic, page URL, redirects, and cache state. | The final URL retains the expected encoded query key and value. |
| Build one minimal documented URL | Build one minimal URL with a single documented key and a simple value, then inspect the final URL after every redirect or canonical rule. | The correct public form field and subfield populate on cached and uncached requests. |
| Test encoding, choices, and subfields | Test text, spaces, Unicode, reserved characters, repeated keys, missing values, dropdown labels, stored values, dynamic choices, and composite subfields separately. | Entry, notification, webhook, and CRM values match the visible selection. |
| Compare uncached, cached, and submitted values | Compare the editor preview, uncached public page, cached public page, mobile browser, AJAX submission, entry value, notification, and CRM payload. | Form duplication or field-ID changes have a versioned URL migration plan. |
What to check first
- Record the live form ID, field ID, field type, subfield name, show-values setting, dynamic choices, conditional logic, page URL, redirects, and cache state.
- Build one minimal URL with a single documented key and a simple value, then inspect the final URL after every redirect or canonical rule.
- Test text, spaces, Unicode, reserved characters, repeated keys, missing values, dropdown labels, stored values, dynamic choices, and composite subfields separately.
- Compare the editor preview, uncached public page, cached public page, mobile browser, AJAX submission, entry value, notification, and CRM payload.
- Document any custom friendly-key mapping and add a regression fixture before duplicating the form or changing field IDs.
Field notes
- Write the expected result before changing anything and keep one repeatable canary fixture for the full test window.
- Record exact versions and UTC timestamps because caches, retries, scheduled actions, and deployments can change the evidence between checks.
- Test the public browser path and the stored server-side result, not only an admin preview or isolated API response.
- Close the task only after the visible workflow, logs, stored record, and relevant downstream system agree.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
# Form 20, field 1
https://example.com/contact/?wpf20_1=Sales%20Inquiry
# Form 20, address field 7, city subfield
https://example.com/contact/?wpf20_7_city=Austin
Why this usually happens
- A custom query key is used where WPForms expects the documented ID-based key.
- The form was duplicated and the old form or field ID remains in campaign URLs.
- A redirect, consent tool, cache rule, or canonical strips the query string before the form renders.
- Choice values and composite subfields are tested as plain text even though their stored contract differs.
Decision rule
Do not debug CRM or tracking until the final public URL, rendered field, submitted entry, and stored value agree for one minimal documented WPForms prefill key.
Production verification checklist
- The final URL retains the expected encoded query key and value.
- The correct public form field and subfield populate on cached and uncached requests.
- Entry, notification, webhook, and CRM values match the visible selection.
- Form duplication or field-ID changes have a versioned URL migration plan.
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Inventory current IDs and field contracts
- Build one minimal documented URL
- Test encoding, choices, and subfields
- Compare uncached, cached, and submitted values
- Version any custom mapping
Mistakes to avoid
- Changing production configuration before recording the exact version, failing request, timestamp, and rollback point.
- Treating a clean dashboard or one successful request as proof while the public page, background job, log, stored record, and downstream system remain unchecked.
- Testing a different role, device, locale, order state, form, cache state, or integration path from the one that users actually reach.
- Leaving debug logging, temporary exclusions, duplicate hooks, helper code, test endpoints, or broad permissions active after the verification window.
Questions teams ask during testing
Can I make this change directly in production?
Start with read-only evidence and use staging for code, update, security, checkout, form, or queue changes. If production is required, use one named canary, a short monitored window, and a tested rollback.
How do I avoid a false positive?
Repeat the same fixture with the same versions, role, URL, device, locale, cache state, and downstream integration. Compare stored evidence rather than relying on a visual impression.
What evidence should I retain?
Keep UTC time, exact versions, URL or record ID, expected and actual result, relevant log lines, change made, rollback point, owner, and final verification. Redact credentials and personal data.
When should I escalate?
Escalate when the site is unavailable, security scope is unclear, checkout or lead capture is affected, several systems disagree, or the next action could destroy evidence.
What to tell the client or owner
Give the owner a concise evidence packet with the affected workflow, exact versions, UTC test time, fixture ID, expected result, actual result, key logs, change made, rollback point, final result, owner, and next review date. Remove credentials and personal data before sharing it.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, security, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, have HandL WP repair the WPForms prefill workflow.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references