Zodiac Tech CRM Docs

Lead forms & mapping

Wizard step 5 — fetch your Meta lead forms, tick the ones to import, and confirm where each answer lands in the CRM.

client admin Easy ⏱ 5 min Updated 2026-10-05

Lead forms & mapping

This is wizard step 5: "Choose your lead forms". Two jobs:

  1. Choose which Meta lead forms to import — the CRM only ingests leads from forms you tick here. Everything else stays in Meta.
  2. Map each form answer to a CRM field — so a Meta form question ("Full name") lands in the right place (first_name, phone, …) instead of a generic blob.

Who this is for

  • Workspace owners and admins finishing Meta setup.
  • Anyone adding a new Meta form later, or fixing a mapping after a test lead failed.

Difficulty: Easy · Time: 5 minutes · Prerequisites: Choose your Page & Ad Account is complete.

Step by step

1. Fetch your forms

  1. In the step, click Find my lead forms.
  2. What happens: the CRM asks Meta for the lead forms on your selected Page and lists them with their names and statuses.
  3. Expected result: your forms appear as checkboxes. If the list is empty, your Page genuinely has no forms yet (create one in Meta Ads Manager first, then click Find my lead forms again).

2. Tick the forms to import

  1. Tick every form you actually advertise with.
    • Only ticked forms are imported. Unticked forms are actively skipped when a lead arrives — by design, so test or obsolete forms never pollute your CRM.
  2. What happens: the selection is saved with an "enabled" marker, and the CRM starts watching exactly those forms.
  3. Expected result: the tick list shows your chosen forms. The warning below the list disappears once at least one form is ticked.

Tick at least one form to start receiving leads If nothing is ticked, the step shows: "Tick at least one form to start receiving leads. You can also come back later." With no form selected, live leads are skipped, not queued.

3. Confirm the field mapping

  1. Review "Where should each answer go in your CRM?" — one row per form question, with a suggested destination already filled in.

  2. Adjust any row if needed. Available destinations:

    Destination Meaning
    first_name / last_name Split name fields
    name Full name, kept as one field
    phone Phone number (used for WhatsApp and calling)
    email Email address
    city Maps to your custom field City
    Don't import Deliberately ignore this answer

  3. Confirm the mapping.

  4. What happens: the mapping is stored and the step completes — this is the last piece of Meta setup.

  5. Expected result: the wizard advances to the sales process step, and Zodiac Tech's dashboard sees forms + mapping confirmed.

4. Skipping this step for now

If your Page has no forms yet (for example, campaigns start next week):

  1. Click the skip option on the step.
  2. What happens: the step settles as SKIPPED and you can finish the rest of setup. Zodiac Tech's team still sees the skip marked on the client dashboard.
  3. When forms exist later, return to the step (or fire a test / submit a real lead after ticking forms) — as soon as forms are selected and mapped, the step auto-upgrades to COMPLETED.

Expected result

  • At least one lead form is selected and its questions are mapped to real CRM fields.
  • New leads from those forms will now enter the CRM via the webhook — verified end to end by Test your setup.

Common mistakes

  • Creating a new Meta form and never adding it here. New forms are not auto-imported. Open the step (or Find my lead forms) and tick it — otherwise its leads are skipped.
  • Leaving the phone question mapped to "Don't import". Phone is the key field for WhatsApp, calling and the test-lead checks. Keep it mapped.
  • Mapping two different questions to the same destination. The last mapping wins and data becomes ambiguous; pick one source per field.
  • Ticking every form "just in case". Unticked forms are skipped for a reason — tick production forms only, or your CRM fills with test leads.
  • Expecting old skipped leads to backfill. The allowlist works at arrival time; leads skipped before you ticked the form are not imported retroactively.

Troubleshooting

Symptom Likely cause Fix
"Find my lead forms" returns nothing No forms exist on the selected Page, or none are active Create/activate the form in Meta, then re-run the fetch
A form you use is missing from the list The form belongs to a different Page Check the Page selected in Choose your Page & Ad Account
Test lead shows a missing field That answer mapped to "Don't import" or to the wrong field Fix the mapping in the step, then send the test lead again
Leads arrive in Meta but not the CRM Form not ticked (skipped by the allowlist) Tick the form, confirm, and check Leads not entering the CRM
Step stuck after mapping Mapping not confirmed Confirm the mapping — selection alone is not enough

Technical details

  • Service: App\Services\LeadSources\MetaLeadFormService — fetchForms() (GET /{page_id}/leadgen_forms, fields id/name/status/questions, limit 100), storeSelection(), suggestMapping(), storeMapping(), applyMapping().
  • Storage: settings.lead_forms on the lead_source_connections row — form_ids (the allowlist), enabled_at (activation marker), plus the confirmed mapping (tenant-level fallback is also consulted).
  • Mapping targets include the standard fields above and custom:-prefixed custom fields; the City destination is the workspace's custom City field.
  • Intake gate: MetaConnector::handleWebhook() skips any form_id outside the allowlist and records "Skipped: lead form {id} is not one of the forms selected…" on the webhook log.
  • Wizard save: selection → suggestMapping() → storeMapping(confirmed: true). Empty selection shows the "choose later" warning and does not complete the step.

Was this page helpful?