Gravity Forms 3.0 introduces an International Formatted phone experience with country selection, visible sub-labels, semantic fieldset and legend markup, accessible country search, and E.164 output. Migrating an existing text or US phone field is not only a visual change. It can alter selectors, validation assumptions, stored values, merge tags, country representation, CRM mappings, deduplication, SMS eligibility, and reporting. International unformatted values also have different validation behavior, so the implementation needs an explicit contract for what the browser accepts and what downstream systems store.
Use this when replacing an existing Phone or text field, adding international leads, filtering countries, or sending phone data to a CRM, call platform, SMS provider, or webhook.
Quick answer
Keep the original field and data until the new field is proven. Define the stored canonical format, normally an E.164 value plus ISO country code when downstream systems support it. Test country search, keyboard navigation, visible labels, default country, pasted dial codes, local numbers, mobile autofill, validation, merge tags, notifications, exports, and CRM mapping. Compare old and new fields with a short dual-write period when migration risk is high.
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 |
|---|
| US and Canada | Shared dial code | Country remains distinct |
| UK and Germany | Local and E.164 input | Canonical output matches |
| Country search | Keyboard and screen reader | Results are announced |
| CRM handoff | ISO plus E.164 | No duplicate or truncation |
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence | Verification |
|---|
| Define canonical phone storage | Document the current field ID, stored values, default country, allowed countries, CSS selectors, merge tags, webhook keys, CRM field type, and SMS normalization rules. | Supported countries accept expected values and reject documented invalid cases. |
| Build country and accessibility fixtures | Test representative countries with shared dial codes, short and long national numbers, pasted plus signs, spaces, punctuation, extensions, mobile autofill, and an unsupported country. | Country search, labels, focus, announcements, contrast, and mobile controls are usable. |
| Map old and new fields | Verify fieldset, legend, sub-labels, country-search announcements, focus order, result count, contrast, error message, and touch target behavior. | Entry, notification, export, webhook, CRM, and SMS systems agree on country and canonical number. |
| Update supported CSS and filters | Compare the displayed value, country ISO code, E.164 merge tag, stored entry, export, notification, webhook payload, CRM record, and deduplication key. | Old field data remains available or mapped for historical records after cutover. |
What to check first
- Document the current field ID, stored values, default country, allowed countries, CSS selectors, merge tags, webhook keys, CRM field type, and SMS normalization rules.
- Test representative countries with shared dial codes, short and long national numbers, pasted plus signs, spaces, punctuation, extensions, mobile autofill, and an unsupported country.
- Verify fieldset, legend, sub-labels, country-search announcements, focus order, result count, contrast, error message, and touch target behavior.
- Compare the displayed value, country ISO code, E.164 merge tag, stored entry, export, notification, webhook payload, CRM record, and deduplication key.
- Filter or reorder countries only through the supported JavaScript filter, then retest translated names, caching, optimization, and repeated AJAX rendering.
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 a cache purge, scheduled action, retry, or deployment can change the evidence between tests.
- Test the real browser and downstream record, not only an admin preview or isolated API call.
- Close the task only after the public workflow, server-side record, and relevant delivery or analytics system agree.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
gform.utils.addFilter('gform/phone/countries', function (data) {
const allowed = ['us', 'ca', 'gb', 'de'];
data.countries = data.countries.filter((country) => allowed.includes(country.iso2));
return data;
});
# Store country ISO and {Phone:1:e164} separately when possible.
Why this usually happens
- The old field stored a display string while the new integration expects E.164.
- CSS targets the previous label and wrapper structure instead of field semantics.
- A country filter runs twice or after the field has already initialized.
- The CRM uses locale-specific parsing and disagrees with the website country selection.
Decision rule
Do not replace a working production phone field until the new country and E.164 values reach every downstream system correctly and accessibility checks pass in the actual form context.
Production verification checklist
- Supported countries accept expected values and reject documented invalid cases.
- Country search, labels, focus, announcements, contrast, and mobile controls are usable.
- Entry, notification, export, webhook, CRM, and SMS systems agree on country and canonical number.
- Old field data remains available or mapped for historical records after cutover.
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.
- Define canonical phone storage
- Build country and accessibility fixtures
- Map old and new fields
- Update supported CSS and filters
- Dual-write, reconcile, and cut over
Mistakes to avoid
- Changing production code, form fields, webhook endpoints, cache settings, or security limits before preserving the failing fixture and current configuration.
- Treating one clean dashboard status as proof even though the browser, PHP process, database, delivery provider, and downstream record have not been reconciled.
- Testing with a different form, role, locale, order state, entry shape, plugin version, or cache state than the workflow users actually reach.
- Leaving debug logs, temporary endpoints, broad permissions, copied secrets, or test notifications active after the verification window closes.
Questions teams ask during testing
Can I test this directly on production?
Read-only checks can be appropriate when access is controlled and output is redacted. Make a backup first, use a named canary record, test state-changing work on staging, define rollback, and schedule any production change for a monitored window.
How do I avoid a false positive?
Match the exact version, request path, form or order ID, role, locale, cache state, and integration path. Repeat the same fixture before and after the change, then compare the saved evidence rather than relying on memory.
What evidence should I keep?
Keep the UTC time, site and plugin versions, fixture ID, expected result, actual result, relevant logs, configuration snapshot, change made, rollback point, and final verification. Remove passwords, tokens, payment details, and personal data.
When should I bring in a specialist?
Escalate when checkout, payments, lead capture, security, customer email, accessibility, or several integrations are affected, or when the safest next step is unclear. A concise evidence packet reduces diagnosis time.
What to tell the client or owner
Give the owner a short evidence packet with the affected workflow, exact versions, UTC test time, fixture ID, expected and actual result, logs, change, rollback point, final result, owner, and next review date. Redact 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 migrate the international phone workflow.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references