Facebook Lead Ads Integration Guide

Connect your LeadMachine account with Facebook Lead Ads to automatically receive leads from your Facebook and Instagram advertising campaigns.

What is the Facebook Lead Ads Integration?

The integration allows you to:

• Automatically receive leads when someone fills out a Facebook Lead Form
• Import historical leads from existing Facebook Lead Ad campaigns
• Track lead source and ad campaign attribution
• Apply tags to Facebook leads for easy segmentation
• Keep Facebook lead data synced with your LeadMachine CRM

How Facebook Lead Ads Work

Facebook Lead Ads are a special ad format that:

1. User sees your ad on Facebook/Instagram
2. User clicks the ad and sees a pre-filled form (using their Facebook profile data)
3. User submits the form without leaving Facebook
4. Lead data is sent to your connected systems (like LeadMachine)

Benefits:

• Lower friction than traditional landing pages
• Pre-filled forms increase completion rates
• Real-time lead delivery
• Works on both Facebook and Instagram

Setup Requirements

Before you start, you need:

• Active LeadMachine account (Admin or Manager role)
• Facebook Business Page with Lead Ads permissions
• Facebook Ad Account with active or planned Lead Ad campaigns

Connecting Your Facebook Page

Step 1: Navigate to Settings

1. Log into LeadMachine as Admin
2. Go to your Company page
3. Click the Settings tab
4. Scroll to Facebook Lead Ads section

Step 2: Start OAuth

1. Click the Connect with Facebook button
2. You'll be redirected to Facebook

Step 3: Authorize on Facebook

1. Log in to Facebook if needed
2. Review the permissions requested:

1. Click Continue
2. Select the Pages you want to connect
3. Click Done

Step 4: Select Your Page

If you manage multiple Pages:

1. You'll see a list of your Facebook Pages
2. Click on the Page you want to connect
3. The connection will be saved

If you manage only one Page:

• It will be automatically selected

Step 5: Verify Connection

After connecting:

• Green checkmark appears next to "Connected Page"
• Page name displays in settings
• "Disconnect" button becomes available

If connection fails:

• Verify you have admin access to the Facebook Page
• Check that Lead Ads permissions are approved
• Try disconnecting and reconnecting
• Contact support if issue persists

Receiving Leads Automatically

Once connected, leads are received automatically via webhook:

1. Someone fills out your Facebook Lead Form
2. Facebook sends notification to LeadMachine (within seconds)
3. LeadMachine fetches full lead details
4. Lead is created in your account with:

Enable automatic processing:

1. Go to Company > Settings > Facebook Lead Ads
2. Toggle Enable Facebook Lead Ads to ON
3. Click Save Settings

Importing Historical Leads

For leads collected before connecting, use manual import:

Step 1: Access Import Page

1. Go to Company > Settings > Facebook Lead Ads
2. Click Import Leads button
3. Or navigate directly to Import from Facebook page

Step 2: Select a Form

1. Choose a Lead Form from the dropdown
2. If forms aren't showing, click Refresh to fetch from Facebook
3. Form shows lead count (number available to import)

Step 3: Configure Import

Tag Assignment (Optional):

1. Check "Add a tag to all imported leads"
2. Choose an existing tag OR
3. Create a new tag (e.g., "Facebook Leads Q4")

Import Count:

• Select how many leads to import per batch
• Facebook limits to 100 per request
• Use "Continue Importing" for more

Step 4: Run Import

1. Click Start Import
2. Wait for processing
3. View results:

Step 5: Continue if Needed

If more leads are available:

1. Click Continue Importing Next Batch
2. Repeat until all leads are imported

Default Tag Configuration

Automatically tag all Facebook leads:

1. Go to Company > Settings > Facebook Lead Ads
2. Find Default Tag for Imported Leads
3. Select a tag from dropdown (your company tags)
4. Click Save Settings

All leads (both webhook and manual import) will receive this tag.

Viewing Facebook Leads

In Leads List

Facebook leads appear like any other lead with:

• Source: facebook
• Tag: Your configured tag (if set)
• Icon: Facebook badge indicator

Filter by Facebook:

1. Go to Leads page
2. Filter by Source = "Facebook"
3. Or filter by your Facebook tag

In Lead Details

On individual lead page:

• Note shows "Imported from Facebook Lead Ads"
• Form name and campaign info in note
• Ad name if available
• Full audit trail of import

Sync History

View import history:

• Check Activity Log in company settings
• Filter by "facebook_pull_leads" action
• See import counts and timestamps

Field Mapping

Facebook Lead Form fields map to LeadMachine as follows:

Custom Questions:

• Custom form fields are stored in the sync record
• Available in the raw_data JSON field
• Can be accessed via database queries if needed

Duplicate Handling

LeadMachine prevents duplicate leads:

By Facebook Lead ID:

• Each Facebook lead has a unique ID
• Same lead can't be imported twice
• Re-importing will skip already-imported leads

By Email:

• During import, checks for existing email
• If email exists in your leads, import skips
• Prevents duplicates across all sources

Troubleshooting

Connection Issues

Problem: Can't connect Facebook

Solutions:

• Verify you're logged into correct Facebook account
• Check you have admin access to the Page
• Ensure Lead Ads permissions are granted
• Try in incognito/private browser
• Clear cookies and try again

No Forms Showing

Problem: Form dropdown is empty

Solutions:

• Click Refresh button to fetch forms
• Verify you have Lead Ad campaigns on the Page
• Check if forms are active (not archived)
• Ensure Page has run Lead Ad campaigns

Leads Not Arriving

Problem: Webhook enabled but no leads coming in

Check:

1. "Enable Facebook Lead Ads" is ON in settings
2. Page is connected (shows green checkmark)
3. Lead Form is associated with connected Page
4. Test with a test lead (Facebook has test tools)

Test a lead:

1. Go to Meta Business Suite
2. Navigate to your Lead Ad campaign
3. Use "Test Lead" feature
4. Verify it arrives in LeadMachine

Import Errors

Problem: Leads fail to import

Common errors:

"Facebook is not connected"

• Connection expired or disconnected
• Reconnect via Company Settings

"Form ID is required"

• No form selected
• Choose a form from dropdown

"Permission denied"

• Your role doesn't allow imports
• Need Admin or Manager role

Missing Data

Problem: Leads imported but missing fields

Cause: User didn't fill optional fields on form

Note: Facebook pre-fills from profile, but users can clear fields. Missing data stays blank in LeadMachine.

Best Practices

Form Design

Create effective Lead Ad forms:

• Keep forms short (3-5 fields)
• Use pre-filled fields when possible
• Add context questions to qualify leads
• Include privacy policy link

Tagging Strategy

Organize Facebook leads:

• Create tags by campaign type
• Tag by form or ad set
• Use tags for follow-up workflows
• Example: "FB - Ebook Download", "FB - Demo Request"

Regular Imports

For high-volume campaigns:

• Run imports daily or weekly
• Don't let leads sit in Facebook
• Fresher leads = better conversion

Lead Follow-Up

Act quickly on Facebook leads:

• Leads expect fast response
• They filled form while browsing
• Longer wait = lower conversion
• Aim for < 1 hour response time

Understanding Facebook Permissions

The integration requests these permissions:

Why these are needed:

• Can't receive leads without leads_retrieval
• Can't subscribe to webhooks without pages_manage_ads
• Need to know which Page to connect

Disconnecting Facebook

How to Disconnect

1. Go to Company > Settings > Facebook Lead Ads
2. Click Disconnect button
3. Confirm disconnection

What happens:

• Webhook subscription removed
• No more automatic leads
• Connection tokens deleted
• Existing leads remain untouched

To reconnect: Click "Connect with Facebook" again.

Removing from Facebook

To fully revoke access:

1. Go to Facebook Settings
2. Navigate to Security > Apps and Websites
3. Find LeadMachine
4. Click Remove

This revokes all permissions - you'll need to reconnect from scratch.

Privacy & Compliance

Data Handling

• Lead data is transmitted securely (HTTPS)
• Data is stored in your LeadMachine database
• You control data retention and deletion
• Follows your company's privacy policy

GDPR Considerations

If serving EU users:

• Ensure your Lead Ad forms have consent checkboxes
• Include privacy policy link in forms
• Honor data deletion requests
• Only import leads with consent

Facebook's Requirements

Facebook requires:

• Privacy policy on your website
• Terms of service
• Legitimate business purpose for lead collection

Getting Help

Support Email: [email protected]

Include in your request:

• Screenshot of any error messages
• Page name and ID (if known)
• What you were trying to do
• Browser and device used

Last Updated: December 2025