On this page
- 01 · What the Lead Ads Testing Tool does
- 02 · What you need before you test
- 03 · How to send a test lead, step by step
- 04 · How to read the status table
- 05 · Check the lead in your CRM, not just in Meta
- 06 · When the test lead fails or never arrives
- 07 · Run it again after every change
- 08 · Why test leads and ad results do not match
- 09 · The pre-launch lead form checklist
- 10 · Questions we get about testing Meta lead forms
- 11 · Sources
What the Lead Ads Testing Tool does
The Lead Ads Testing Tool is a free Meta developer tool at developers.facebook.com/tools/lead-ads-testing. You choose a Facebook Page and one of its instant forms, click Create Lead, and Meta submits a test lead through that form exactly as a real one would arrive. You then click Track Status to see whether Meta delivered it to your integration, and check your CRM, Zapier or email alert to confirm it landed.
Run it on every new form and after any change to your CRM connection, field mapping or Page permissions. It costs nothing, needs no live ad and takes about five minutes. The alternative is finding out from a client a week later that forty paid leads went nowhere.
Meta's developer documentation sets three rules worth knowing before you start: you need a Page role of Advertiser or above on the Page that owns the form, you can hold only one test lead per form at a time, and test leads are organic leads that are not attached to any ad.
What you need before you test
- A published instant form on the right Page. The form drop-down only lists forms that belong to the Page you selected. If the form was built on a different Page, it will not appear.
- Advertiser access or higher on that Page. The Page drop-down lists only Pages where your Facebook profile can advertise.
- Your CRM or Zapier connection already set up. In Meta Business Suite go to All tools, then Instant forms, then the CRM setup tab, search for your CRM and connect it. Meta notes that only Page admins with leads access permission can connect a CRM.
- Leads access checked. If anyone has customised leads access for your business portfolio, new people and CRMs must be added by hand before they receive leads. We cover where to look below.
- If you built your own app: your webhook endpoint is subscribed to the Page's leadgen field. Meta's docs say the testing tool cannot be used in developer mode, so set the app to Live first.
How to send a test lead, step by step
- Log in to Facebook with the profile that has access to the Page, then go to developers.facebook.com/tools/lead-ads-testing.
- In the Page drop-down, select the Page that owns the form.
- In the Form drop-down, select the form you are about to advertise.
- Click Create Lead to send a lead filled with dummy data, or click Preview Form first and type your own answers. We use Preview Form so the test carries a real email address and a phone number we can call, which proves the follow-up works and not only the data transfer.
- Once the lead is created, a Track Status button appears. Click it. Meta says the real-time update takes a few seconds to fire, so click again until the status changes from pending.
- Open your CRM, Zapier history or inbox and find the lead.
Use an obvious name in Preview Form, such as TEST Sage Delete, so nobody on the sales team calls it as a real enquiry and it is easy to filter out of reports.
How to read the status table
| Status | What it means | What we do next |
|---|---|---|
| pending | Meta has not yet sent the real-time update to the integration. | Wait a few seconds and click Track Status again. If it stays pending for more than a few minutes, check that an integration is subscribed to the Page at all. |
| success | Meta delivered the update. The table shows a copy of the payload it sent. | Go to the CRM and confirm the lead exists with every field. Success in Meta only proves Meta sent it. |
| failed | Delivery to the integration failed. | Read the error_code column, then work through the fixes below. |
While you are here, check which integrations the Page is connected to. An old CRM or a tool left behind by a previous agency can receive the same lead as your current one, which is how duplicate contacts and double follow-up calls start. Remove anything you no longer use.
Check the lead in your CRM, not just in Meta
A green success line is half the test. The point is a lead your team can act on, so check these in the CRM itself:
- Every form field arrived in the right CRM field. Custom questions are the usual gap. If you added a question such as Which suburb are you in?, it needs its own mapping.
- The lead has an owner and a stage. It should land assigned to a person, in the pipeline stage you use for new enquiries.
- The alert fired. Whoever calls leads back should get the notification on their phone, within a minute or two.
- Source fields are filled. Test leads are not tied to an ad, so ad, ad set and campaign IDs will be blank on the test. On real leads they should populate, and that is what lets you report qualified leads by ad later.
Worked example: a Melbourne physio clinic connects its instant form to its CRM through Zapier. The test shows success in Meta and the contact appears in the CRM, but the Preferred clinic answer is missing and the alert goes to an inbox nobody checks on weekends. Both are fixed in ten minutes before launch. Found after launch, they would have cost a weekend of paid enquiries sitting unanswered.
If you want help mapping what happens after the lead lands, our Meta lead form follow-up process covers ownership, speed to call and outcomes.
When the test lead fails or never arrives
Status is failed
Start with leads access. In Meta Business Suite, open Settings for your business portfolio, go to Integrations, then Leads access. If access has been customised, the CRM must be listed on the CRMs tab or Meta will not notify it. Click Assign CRMs and add it. Meta also notes that a custom CRM fetches lead data with a user or Page access token, and that fetch fails when the person behind the token does not have leads access. Add that person on the People tab.
Status is success but nothing is in the CRM
Meta delivered the update and the problem is on the CRM side. Check the CRM's integration log or Zapier task history for a rejected record. The common causes are a required CRM field that the form does not collect, a phone number in a format the CRM refuses, or a filter step that drops the lead.
The Page or form is missing from the drop-downs
Your profile needs Advertiser access or higher on the Page, and the form must belong to that Page. Forms are created per Page, so a form built on a staging or old brand Page will not show.
Create Lead does nothing or returns an error
There is probably already a test lead on that form. Click Delete Lead and create a new one. If you built your own app, check it is not in developer mode.
Your integration was connected through an outside website
Meta says CRMs connected through an external site cannot be edited or disconnected from Meta Business Suite. Fix the connection in the CRM provider's own settings.
Run it again after every change
Meta allows one test lead per form. To run another test, click Delete Lead in the tool, then create a new one. Only the person who owns the test lead can delete it. If you work through the API, Meta's docs give a POST to /{form_id}/test_leads to create one and a DELETE on the lead ID to remove it, with a Page access token.
We retest after any of these: a new form or a duplicated form, a new custom question, a change to the CRM mapping or Zapier steps, a new person or agency added to the Page, and any change to leads access. Each one can break delivery without anything looking different in Ads Manager.
Why test leads and ad results do not match
Test leads are organic, so they are not counted in the Results column in Ads Manager and do not cost anything. Meta's help centre notes they still appear in the lead file you download from Meta Business Suite, even if your form's sharing setting is Restricted. Delete or filter them before you count leads for a client report.
Two more differences are worth knowing. Meta keeps leads available for download for 90 days from when each form was submitted, so a lifetime campaign can show more results than you can download. And a lead submitted from an ad preview, or downloaded by someone without advertiser access on the ad account, can arrive without ad IDs. A CRM connection that you have tested is the reliable record, which is why we connect one before launch rather than relying on downloads.
Once leads arrive cleanly, the next step is sending outcomes back to Meta. Our guide to Meta offline conversion tracking shows how to return qualified and won leads so Meta finds more of them, and Meta customer lists that update themselves keeps existing customers out of your prospecting. If lead volume is fine but quality is not, start with how to improve paid ad lead quality.
We run this test on every lead form we launch for clients. If you would rather hand the setup and follow-up system to us, that is the work we do every day.
The pre-launch lead form checklist
- Form is published on the Page the ad will run from.
- CRM or Zapier connected in Meta Business Suite, Instant forms, CRM setup.
- Leads access lists the CRM and any person behind a custom integration's token.
- Test lead sent with Preview Form, using an obvious test name and a real phone number.
- Track Status shows success.
- Lead found in the CRM with every field, an owner, a stage and an alert.
- Someone called the test number back, as they would a real enquiry.
- Test lead deleted in the tool and removed from the CRM.
- Ad creative and form previewed together in the Meta ads preview tool so the promise in the ad matches the form.
Questions we get about testing Meta lead forms
Where is the Meta Lead Ads Testing Tool?
At developers.facebook.com/tools/lead-ads-testing. Log in with a Facebook profile that has Advertiser access or higher on the Page that owns the form, then choose the Page and form from the drop-downs.
Do test leads cost money or count as results?
No. Leads from the testing tool are organic and not attached to any ad, so there is no charge and they are not counted in the Results column in Ads Manager. They can still appear in the lead file downloaded from Meta Business Suite.
Why can I only create one test lead?
Meta allows one test lead per form at a time. Click Delete Lead in the tool, then create a new one. Only the person who created the test lead can delete it.
Why is the Lead Ads Testing Tool not working?
Check that your profile has Advertiser access or higher on the Page, that the form belongs to that Page, and that there is no existing test lead on the form. If the status shows failed, check leads access in Meta Business Suite settings, under Integrations, and make sure your CRM is assigned. Meta's docs also say the tool cannot be used in developer mode.
Can I test a lead form without the developer tool?
You can submit the form from an ad preview, but that lead can arrive without ad IDs and is easy to mix up with real enquiries. The testing tool shows whether Meta delivered the lead to your integration, and the error code if it failed, which a preview cannot tell you.
How long do I have to download real leads?
Meta keeps leads available for download for 90 days from when each form was submitted. Connect a CRM so every lead is stored as it arrives.
Sources
- Meta for Developers: Lead ads testing and troubleshooting
- Meta for Developers: Retrieving leads
- Meta Business Help Centre: Connect your CRM system to Meta Business Suite
- Meta Business Help Centre: Assign or remove permissions in leads access
- Meta Business Help Centre: About leads access in Meta Business Suite
- Meta Business Help Centre: About organic leads
- Meta Business Help Centre: About expired leads