Gravity Forms International Phone Number Mask Input Addon

Add an international phone field to Gravity Forms with a country flag picker, a live input mask and validation. Visitors search for their country by name or dial code, the mask adjusts to that country, and the number is checked as they type. Numbers are saved in standard E.164 format, ready for SMS, CRM and calling tools. This guide covers installation, country defaults, IP-based detection, country lists and output formats.

Core Capabilities & Formatting Architecture

Standard phone fields frequently capture malformed entries (e.g., missing area codes, incorrect digit counts, or omitted international dialing prefixes). This leads to bounced SMS campaigns and failed sales calls.

The International Phone Number Mask Input addon transforms the user experience by automatically preselecting the visitor’s home country via GeoIP, rendering a high-resolution flag selector, applying real-time national digit masks as the visitor types, and saving standardized E.164 strings (e.g., +14155552671) directly into Gravity Forms entry storage.

Step 1: Installation & Commercial License Activation

Download the plugin ZIP file from your Gravity Extra customer portal. In your WordPress admin, go to Plugins → Add New → Upload Plugin, choose the downloaded ZIP file, and click Install Now followed by Activate Plugin.

Navigate to Forms → Settings → Phone Number Mask to activate your commercial license key. This ensures automatic updates, compatibility with latest WordPress core releases, and direct support access.

Step 2: Adding the International Phone Field to Your Form

Open any form in the Gravity Forms editor. You can either enhance an existing Phone field or drag a new Phone field from the Advanced Fields toolbox onto your form canvas.

Step 3: Enabling International Masking & Country Selector

In the field settings panel on the right, open the Phone Format section. Select International (Flag Dropdown) to activate the advanced formatting engine.

1. Default Country & Preferred Countries

Choose a fallback default country (e.g., United States or United Kingdom) for visitors when geolocation is unavailable. You can also specify a comma-separated list of Preferred Countries (e.g., us, gb, ca, au) to pin frequently chosen regions at the very top of the dropdown menu.

2. Automatic IP Geolocation Country Detection

Enable the Auto-Detect Country by IP toggle. When a visitor arrives on your page, the script instantly determines their geographic location and preselects their national flag and international dial code without requiring manual selection.

To enable IP-based country detection, obtain a free access token from IPInfo.io and paste it under Forms → Settings → Phone Number Mask.

Step 4: Country Whitelisting & Output Standardization

Control which nations can submit your form and standardize output formats for your CRM and marketing automations:

1. Country Whitelist (Only Countries) & Blacklist (Exclude Countries)

If your business operates exclusively within select territories (e.g., North America or the European Union), restrict the dropdown to display only approved countries by entering their 2-letter ISO codes.

2. Standardized Storage Formats (E.164, National, International)

Choose how the phone number is stored in your database upon form submission:

Output Format	Example Stored Value	Ideal Integration Use Case
E.164 (Recommended)	+14155552671	Twilio, WhatsApp API, HubSpot, Salesforce, SMS Gateways.
International	+1 415-555-2671	Human-readable customer service emails and PDF generation.
National	(415) 555-2671	Domestic-only internal workflows and local printing.
RFC3966	tel:+1-415-555-2671	Click-to-call mobile hyperlinks and telephony systems.

Step 5: Dynamic Input Masking & Real-Time Validation

As the visitor types, the add-on dynamically applies the exact spacing and punctuation rules of the selected country (e.g., (555) 000-0000 for US/Canada, 07123 456789 for UK). If an invalid number of digits is entered, real-time client-side and server-side validation catches the error before form submission.

Step 6: Form Entry Storage & Notification Merge Tags

When the form is submitted, the validated phone number is stored in the entry record and accessible via standard Gravity Forms merge tags (e.g., {Phone:3}) for email notifications, Webhooks, Zapier, and SMS add-ons.

Countries and Stored Format per Phone Field (version 1.6)

Open the form, click a Phone field that uses the International format with Active Mask on, and find Countries and stored format in the General tab. Every Phone field has its own settings, so a form can have a local mobile field and a worldwide office field.

• Default country: the country shown first when the visitor’s country is not known (no IP detection). “Automatic (as before)” keeps the earlier behaviour.
• Countries at the top of the list: 2-letter codes such as gb, ie, fr. They are shown first, then all other countries.
• Countries accepted: “Only these countries” shows only the countries you list; “All countries except these” hides the ones you list. The number is also checked on the server when the form is sent, so a number from another country is refused even when the list is bypassed.
• Save the number as: E.164 +442079460958 (default, best for SMS and CRM tools), International +44 20 7946 0958, National 020 7946 0958 or a link tel:+44-20-7946-0958. The value is saved in the entry and used by merge tags in notifications.

Fields you do not change work exactly as before. The new settings need an active licence key.

Troubleshooting & Common Issues

Issue Encountered	Probable Cause	Recommended Resolution
Flags not displaying / broken icons	CSS or asset path conflict with caching plugins.	Purge server and plugin caches. Ensure SVG/PNG asset loading is not blocked by security headers.
GeoIP detects wrong country on local test	Localhost IP (127.0.0.1) has no geographic location.	Test on a live staging or production URL with a public IP address.
Form fails validation on valid national numbers	Leading zero conflict in international dialing.	Enable the Auto-strip leading zero option in the field settings for countries like the UK, Australia, and Italy.

Frequently Asked Questions (FAQ)