> For the complete documentation index, see [llms.txt](https://whatsnap.gitbook.io/whatsnap-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whatsnap.gitbook.io/whatsnap-docs/faq/general/phone-number-validation.md).

# How to Validate Phone Numbers in GoHighLevel

Learn how to validate phone numbers in GoHighLevel before sending messages through WhatSnap.  Improve deliverability, avoid errors, and ensure contacts can receive your messages.

Ensure your contacts can actually receive messages before you hit send. Learn how to automatically validate phone numbers inside GoHighLevel using simple automation and affordable third-party services.

***

## Why Phone Validation Matters

### The Problem

GoHighLevel (and WhatSnap) have built-in validation — but **only after the first message is sent**. This creates problems when:

* ❌ Importing large contact lists
* ❌ Running database reactivation campaigns
* ❌ Starting cold outreach
* ❌ Cleaning up old contact data

**Issues You'll Face:**

* Wasting messages on landlines
* Failed deliveries to fake/invalid numbers
* Lower deliverability rates
* Potential account issues with carriers
* Poor campaign performance metrics

### The Solution

**Pre-validate phone numbers** before sending any messages using:

1. Automated workflow validation (US numbers)
2. Third-party API services (all countries)
3. Simple conditional logic (basic validation)

***

## Method 1: US Phone Validation Using PhoneValidator

### Overview

**Best for:** US-based contacts, database reactivations, large imports

**Service:** [PhoneValidator.com](https://phonevalidator.com)

**Cost:** \~$0.004 per contact

* Validate 1,000 contacts = **$4**
* Validate 10,000 contacts = **$40**

**What It Detects:**

* ✅ Landlines (can't receive SMS)
* ✅ VOIP numbers (may have issues)
* ✅ Fake/disconnected numbers
* ✅ Whether number can receive SMS
* ✅ Carrier information

***

### Video Tutorial

Watch this step-by-step guide on implementing phone validation in GoHighLevel:

{% embed url="<https://youtu.be/r1X2rHvFGYc>" %}
How to Validate Phone Numbers in HighLevel Using PhoneValidator
{% endembed %}

***

### Real-World Example

**Scenario:** A contact books an appointment and enters a landline number. GoHighLevel doesn't flag it until after you send a message, resulting in:

* Failed SMS delivery
* Contact misses appointment reminders
* Lower show-up rate

**With Validation:**

1. Contact is created with landline number
2. Workflow validates number automatically
3. Detects it's a landline (not textable)
4. System sends **email** instead asking for mobile number
5. Contact updates to mobile number
6. Appointment reminders now successfully delivered via SMS

{% hint style="success" %}
**Pro Tip**: If a number is non-textable, use automation to send an email requesting an updated mobile number. This keeps your communication flowing!
{% endhint %}

***

### How It Works

**Workflow Overview:**

{% @mermaid/diagram content="graph TD;
A\["Contact Created"] --> B\["Wait 1 sec<br/>(Drip Delay)"];
B --> C\["API Call:<br/>PhoneValidator"];
C --> D{"Is Textable?"};
D -->|Yes| E\["Add Tag:<br/>Textable-Yes"];
D -->|No| F\["Add Tag:<br/>Textable-No"];
F --> G\["Enable DND<br/>for SMS"];
F --> H\["Send Email:<br/>Request Mobile"];
E --> I\["Continue with<br/>SMS Workflows"];

```
classDef input fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#000000;
classDef process fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000000;
classDef decision fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#000000;
classDef success fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px,color:#000000;
classDef error fill:#ffebee,stroke:#c62828,stroke-width:2px,color:#000000;

class A input;
class B,C process;
class D decision;
class E,I success;
class F,G,H error;" %}
```

***

### Setup Instructions

{% stepper %}
{% step %}

#### Sign Up for PhoneValidator

1. Visit [PhoneValidator.com](https://phonevalidator.com)
2. Create an account
3. Deposit $10 to get started (lasts for \~2,500 validations)
4. Navigate to **API Keys** section
5. Copy your API key

**Keep your API key handy** - you'll need it in the next steps.
{% endstep %}

{% step %}

#### Download Free Snapshot

Get the pre-built workflow automation:

**Download Link:** [PhoneValidator Snapshot](https://highlevelfreaks.com/phone-validator)

**What's Included:**

* ✅ Pre-configured workflow automation
* ✅ Custom value setup for API key
* ✅ Webhook configuration
* ✅ Decision tree logic
* ✅ Tag automation
* ✅ DND management

{% hint style="info" %}
**Alternative**: You can build the workflow manually following the steps in this guide, but the snapshot saves significant setup time.
{% endhint %}
{% endstep %}

{% step %}

#### Import Snapshot to GoHighLevel

1. Log in to your **GoHighLevel account**
2. Navigate to **Settings** → **Snapshots**
3. Click **"Import Snapshot"**
4. Upload the PhoneValidator snapshot file
5. Select the sub-account to import into
6. Click **"Import"**

Wait for import to complete (usually 30-60 seconds).
{% endstep %}

{% step %}

#### Configure API Key

1. Go to **Settings** → **Custom Values**
2. Find **"PhoneValidator\_API\_Key"** custom value
3. Paste your PhoneValidator API key
4. Click **"Save"**

This stores your API key securely and makes it available to the workflow.
{% endstep %}

{% step %}

#### Review Workflow

Navigate to **Automations** → **Workflows** and open the PhoneValidator workflow.

**Key Components:**

**1. Trigger: Contact Created**

* Runs whenever a new contact is added
* Can also manually add existing contacts to workflow

**2. Drip Scheduling**

* Processes **25 contacts every 2 seconds**
* Prevents API rate-limit errors
* Ensures smooth bulk processing

**3. Webhook Action**

* Sends phone number to PhoneValidator API
* Includes your API key
* Receives validation response

**4. Decision Tree**

* Checks if number is textable
* Routes to appropriate actions
* Handles errors gracefully

**5. Tag Actions**

* `Textable: Yes` - Can receive SMS
* `Textable: No` - Cannot receive SMS (landline, VOIP, invalid)

**6. DND Management**

* Automatically enables DND for SMS on non-textable numbers
* Prevents wasted messages

**7. Email Notification (Optional)**

* Sends email requesting mobile number update
* Only for non-textable numbers
  {% endstep %}

{% step %}

#### Test the Workflow

**Create test contacts:**

**Test #1: Valid Mobile Number**

1. Create new contact with your mobile number
2. Watch workflow execute
3. Check that tag `Textable: Yes` is added
4. Verify contact can receive SMS workflows

**Test #2: Landline Number**

1. Create contact with a known landline (e.g., local business)
2. Watch workflow execute
3. Check that tag `Textable: No` is added
4. Verify DND for SMS is enabled
5. Check if email was sent (if configured)

**Test #3: Invalid Number**

1. Create contact with fake number (e.g., 555-0100)
2. Watch workflow execute
3. Check tagging and DND

{% hint style="success" %}
**Success!** If tags are applied correctly, your validation is working. You can now use these tags in smart lists and campaigns.
{% endhint %}
{% endstep %}
{% endstepper %}

***

### Using Validated Data

#### Create Smart Lists

**Textable Contacts:**

1. Go to **Contacts** → **Smart Lists**
2. Create new smart list: **"Textable Contacts"**
3. Add filter: **Has tag** `Textable: Yes`
4. Use this list for SMS campaigns

**Non-Textable Contacts:**

1. Create smart list: **"Non-Textable Contacts"**
2. Add filter: **Has tag** `Textable: No`
3. Use this list for:
   * Email campaigns
   * Data cleanup
   * Manual outreach
   * Deletion (if desired)

#### Exclude Non-Textable from Campaigns

When creating SMS campaigns in WhatSnap:

1. Select your contact list
2. Add **exclusion filter**: **Does NOT have tag** `Textable: No`
3. Or: Use **"Textable Contacts"** smart list directly

**Result:** Only valid, textable numbers receive your SMS campaigns.

***

### Bulk Validate Existing Contacts

**For contacts already in your system:**

1. Navigate to the **PhoneValidator workflow**
2. Click **"Add Contacts"** or **"Bulk Enroll"**
3. Select contact list or smart list to validate
4. Confirm enrollment

**Processing:**

* Workflow processes **25 contacts every 2 seconds**
* 1,000 contacts = \~80 seconds
* 10,000 contacts = \~13 minutes

**Monitor Progress:**

* Check workflow execution logs
* Watch tags being applied
* Review any errors

{% hint style="warning" %}
**Cost Consideration**: Bulk validation costs $0.004 per contact. Calculate costs before bulk enrolling large lists (e.g., 10,000 contacts = $40).
{% endhint %}

***

### Advanced: Email Request for Updated Number

**If contact has non-textable number:**

**Setup Email Automation:**

1. Add **"Send Email"** action after `Textable: No` tag
2. Create email template:

**Subject:** Update Your Contact Information

**Body:**

```
Hi {{contact.first_name}},

We noticed the phone number we have on file ({{contact.phone}}) may not 
be able to receive text messages.

To ensure you receive important updates and reminders via SMS, please 
reply to this email with your mobile number.

Thank you!

[Your Business Name]
```

3. Add **"Wait for Email Reply"** action (optional)
4. Parse reply to extract new number
5. Update contact phone field
6. Re-trigger validation workflow

***

## Method 2: International Phone Validation Using Workflows

### Overview

**Best for:** Contacts outside the US, countries with specific mobile prefixes

**Cost:** $0 (uses built-in workflow logic)

**What It Does:**

* Validates based on country code and mobile prefix patterns
* Simple, free alternative for specific countries
* No third-party service required

**Supported Countries:**

* 🇦🇺 Australia
* 🇬🇧 United Kingdom
* 🇨🇦 Canada
* Others (if you know mobile prefixes)

***

### How It Works

**Country-Specific Mobile Prefixes:**

**Australia 🇦🇺:**

* All mobile numbers start with `04`
* International format: `+614` (e.g., +614XXXXXXXX)

**United Kingdom 🇬🇧:**

* Common mobile prefixes: `75`, `77`, `79`
* International format: `+4475`, `+4477`, `+4479`

**Canada 🇨🇦:**

* Mobile numbers not easily distinguished from landlines
* Use same approach as US (PhoneValidator API)

***

### Setup Instructions

{% stepper %}
{% step %}

#### Create Validation Workflow

1. Go to **Automations** → **Workflows**
2. Click **"Create Workflow"**
3. Name: **"Phone Validation - \[Country]"**
4. Trigger: **"Contact Created"** or **"Tag Added"**
   {% endstep %}

{% step %}

#### Add If/Else Condition

1. Add **"If/Else"** action
2. Configure condition for your country:

**For Australia:**

```
If phone number contains: +614
Then: Textable (mobile)
Else: Not textable (landline or invalid)
```

**For UK:**

```
If phone number contains: +4475
OR phone number contains: +4477
OR phone number contains: +4479
Then: Textable (mobile)
Else: Not textable (landline or invalid)
```

**For Other Countries:** Research mobile prefixes and add similar logic.
{% endstep %}

{% step %}

#### Add Actions

**If Textable (Yes Branch):**

1. Add **"Add Tag"** action: `Textable: Yes`
2. (Optional) Add to SMS campaign list

**If Not Textable (No Branch):**

1. Add **"Add Tag"** action: `Textable: No`
2. Add **"Do Not Disturb"** action: Enable for SMS
3. (Optional) Send email requesting mobile number
   {% endstep %}

{% step %}

#### Test & Activate

1. Create test contacts with mobile and landline numbers
2. Verify tags are applied correctly
3. Activate workflow
4. Enroll existing contacts if needed
   {% endstep %}
   {% endstepper %}

***

### Example: Australia Mobile Validation

**Workflow Logic:**

```
Trigger: Contact Created
    ↓
Wait: 1 second
    ↓
If/Else: Does phone contain "+614"?
    ↓
YES → Add Tag "Textable: Yes" → Continue to SMS workflows
    ↓
NO → Add Tag "Textable: No" → Enable DND (SMS) → Send email
```

**Prefixes to Check:**

* `+614` - Australian mobile
* `+61` (without 4) - Australian landline

***

### Limitations

**⚠️ This Method:**

* Only validates format, not if number is active
* Cannot detect disconnected numbers
* Cannot detect VOIP numbers
* Requires consistent international formatting
* Less accurate than API validation

**✅ Best For:**

* Basic validation when budget is limited
* Countries with clear mobile prefix patterns
* Supplementing API validation
* Initial contact import cleanup

***

## Method 3: Basic Format Validation

### Simplest Option (Free)

**Use GoHighLevel's built-in validation:**

**When Contact is Created:**

1. Check if phone number is present
2. Check if properly formatted
3. Check minimum/maximum length
4. Tag accordingly

**Workflow Logic:**

```
If phone number is empty
    → Add tag "No Phone"
    → Stop SMS workflows

If phone number length < 10
    → Add tag "Invalid Phone"
    → Request phone update

If phone number is valid format
    → Add tag "Phone Validated"
    → Continue workflows
```

**Limitations:**

* Doesn't detect landlines
* Doesn't verify if number is active
* Basic validation only

***

## Best Practices

### 1. Validate at Point of Entry

**Ideal Validation Points:**

* ✅ When contact is created
* ✅ After form submission
* ✅ When importing contacts
* ✅ Before starting campaigns

**Workflow Trigger Options:**

* Contact created
* Tag added: "New Import"
* Contact updated (phone field)
* Manual enrollment

***

### 2. Use Smart Lists for Segmentation

**Create Targeted Lists:**

**List 1: "SMS Ready"**

* Has tag `Textable: Yes`
* Does NOT have DND for SMS
* Has valid mobile number

**List 2: "Email Only"**

* Has tag `Textable: No`
* OR: Does not have phone number
* Use for email campaigns

**List 3: "Needs Phone Update"**

* Has tag `Textable: No`
* Has email address
* Sent "request number" email

***

### 3. Regular List Cleaning

**Monthly or Quarterly:**

1. Run validation on all contacts
2. Identify and remove invalid numbers
3. Request updates from non-textable contacts
4. Archive contacts with no valid contact method

**Database Hygiene:**

* ✅ Improves deliverability
* ✅ Reduces wasted messages
* ✅ Lowers costs
* ✅ Better campaign metrics

***

### 4. Combine with WhatSnap Features

**For WhatSnap Users:**

**Validate Before Campaign:**

1. Import contact list to GHL
2. Run validation workflow
3. Create smart list: "Textable Contacts"
4. Create WhatSnap campaign using smart list
5. Higher deliverability, fewer failures

**Multi-Platform Routing:**

* Use WhatsApp for international contacts (less validation needed)
* Use SMS for validated US mobile numbers
* Use email for non-textable contacts

***

## Cost Comparison

| Method                 | Cost           | Accuracy  | Speed     | Best For                        |
| ---------------------- | -------------- | --------- | --------- | ------------------------------- |
| **PhoneValidator API** | $0.004/contact | Very High | Fast      | US numbers, large lists         |
| **Workflow Logic**     | $0             | Medium    | Fast      | International, budget-conscious |
| **Basic Format**       | $0             | Low       | Very Fast | Initial cleanup                 |

**Recommendation:**

* **US contacts**: PhoneValidator API (most accurate)
* **International**: Workflow logic (free, reasonable accuracy)
* **Budget projects**: Basic format validation (better than nothing)

***

## ROI of Phone Validation

### Example: 10,000 Contact Database Reactivation

**Without Validation:**

* 10,000 contacts × $0.004 (avg SMS cost via WhatSnap SIM) = \~$40
* \~15% are landlines/invalid = **1,500 wasted messages** = \~$6 wasted
* Plus: Poor deliverability metrics, potential carrier issues

**With Validation ($40 cost):**

* Validate 10,000 contacts = **$40**
* Identify 1,500 non-textable
* Send SMS to only 8,500 valid mobiles = **$34**
* **Avoid $6 in wasted messages**
* **Improve deliverability** (85% → 95%+)
* **Better campaign metrics**
* **Prevent carrier issues**

**Net Cost:** $40 validation - $6 saved = $34 net cost **Benefit:** Much higher deliverability, cleaner data, better results

{% hint style="success" %}
**Worth It**: Phone validation pays for itself in improved deliverability, better metrics, and avoiding carrier issues. For database reactivations, it's essential.
{% endhint %}

***

## Troubleshooting

### PhoneValidator API Issues

**Issue: Webhook returns error**

* ✅ Check API key is correct
* ✅ Verify you have credits in PhoneValidator account
* ✅ Check phone number formatting (international format)
* ✅ Review PhoneValidator API documentation

**Issue: Workflow not executing**

* ✅ Check workflow is activated
* ✅ Verify trigger conditions are met
* ✅ Review workflow logs for errors
* ✅ Test with single contact first

**Issue: Rate limit errors**

* ✅ Increase drip delay (e.g., 25 every 5 seconds)
* ✅ Process smaller batches
* ✅ Contact PhoneValidator support for rate limit increase

***

### Workflow Logic Issues

**Issue: Not detecting mobile numbers**

* ✅ Ensure phone numbers are in international format (+CountryCode)
* ✅ Check mobile prefix patterns are correct
* ✅ Test with known mobile and landline numbers
* ✅ Review condition logic (case-sensitive)

**Issue: Tags not applying**

* ✅ Check tag names match exactly
* ✅ Verify tag actions are in correct workflow branches
* ✅ Review workflow execution logs
* ✅ Test with single contact manually

***

## Summary

**Phone validation is essential for:**

* ✅ Database reactivation campaigns
* ✅ Large contact imports
* ✅ Improving deliverability
* ✅ Avoiding wasted messages
* ✅ Better campaign metrics

**Methods:**

1. **PhoneValidator API** - Most accurate, paid ($0.004/contact)
2. **Workflow Logic** - Free, country-specific validation
3. **Basic Format** - Simplest, least accurate

**Best Practice:**

* Validate at point of entry
* Use smart lists for segmentation
* Clean database regularly
* Combine with WhatSnap multi-platform routing

{% hint style="success" %}
**Get Started**: Download the [free PhoneValidator snapshot](https://highlevelfreaks.com/phone-validator) and start validating contacts today. Your deliverability will thank you!
{% endhint %}

***

## Related Resources

* [Database Reactivations](broken://pages/1NpMBh9RXUeVt9ElFXvj) - Best practices for DBR campaigns
* [SMS Campaign Benefits](/whatsnap-docs/faq/sms/sms-campaign-benefits.md) - Maximize SMS effectiveness
* [Campaign Overview](/whatsnap-docs/outreach/campaign-overview.md) - Create effective campaigns
* [Workflow Automation](/whatsnap-docs/conversations/workflow-automation.md) - Automate messaging

***

**Questions about phone validation?** Contact <support@whatsnap.ai> or join our community for help setting up validation workflows.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://whatsnap.gitbook.io/whatsnap-docs/faq/general/phone-number-validation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.