# Facebook Lead Forms

Running Facebook ads to capture leads? This integration automatically sends those leads into <span data-t="appName">DM Champ</span> so you can follow up with them via WhatsApp, SMS, or any other connected channel — without lifting a finger.

It works by connecting Facebook Lead Ads to <span data-t="appName">DM Champ</span> through an automation platform (such as Pabbly, Zapier, or Make). These platforms act as a bridge between Facebook and <span data-t="appName">DM Champ</span>, passing lead information from one to the other using the API (a way for different software to exchange data automatically).

---

## Prerequisites

Before you start, make sure you have:

- **Facebook Ads Manager** access with permission to create Lead Ads.
- **An account** with an active API key (generate one at **Settings → Integrations → API Key** — see [API Access](api-access.md) for the exact steps).
- **An automation platform** account — Pabbly Connect, Zapier, or Make (Integromat). This guide uses Pabbly as the example, but the steps are similar on any platform.
- **A contact list** in <span data-t="appName">DM Champ</span> where new leads will be added — see [Organizing Lists & Contacts](../get-started/list-and-contact-management.md).

---

## Overview

The integration works in three stages:

1. A prospect fills out your Facebook Lead Form.
2. Your automation platform detects the new lead and sends the information to <span data-t="appName">DM Champ</span> automatically (using two API calls).
3. <span data-t="appName">DM Champ</span> creates the contact and adds them to the list you specify.

From there, a broadcast, a campaign, or an AI Agent you've assigned handles the rest — whether that's an AI-powered welcome message, a drip sequence, or a manual follow-up.

---

## Step 1: Create Your Facebook Lead Form

1. Open **Facebook Ads Manager**.
2. Create a new campaign with the **Leads** objective.
3. At the ad level, choose **Instant Form** as the lead method.
4. Build your form with the fields you need. At minimum, include:
   - **First name**
   - **Phone number** (with country code)
   - Optional: Last name, email
5. Publish the ad or save the form as a draft for testing.

---

## Step 2: Test the Lead Form

Before connecting the automation, submit a test lead:

1. In Ads Manager, go to your Lead Form.
2. Click **Preview** and fill out the form with test data.
3. Confirm the test lead appears in your **Facebook Lead Center** (under Publishing Tools on your Facebook Page, or in Ads Manager under "Leads").

This test entry will be used to set up the field mapping in your automation platform.

---

## Step 3: Set Up the Automation

### Connect Facebook Lead Ads as the Trigger

1. Log in to your automation platform (Pabbly, Zapier, or Make).
2. Create a new workflow / scenario / zap.
3. Set the **trigger** to "Facebook Lead Ads - New Lead."
4. Connect your Facebook account and select the Page and Lead Form.
5. Fetch the test lead to confirm the connection works and to map fields.

### Configure API Call 1: Create Contact

Add an action step with an HTTP / Webhook / API Request:

- **Method:** `POST`
- **URL:** `https://api.dmchamp.com/v1/contacts?apiKey=YOUR_API_KEY`
- **Headers:**
  ```
  Content-Type: application/json
  ```
- **Body (JSON):**
  ```json
  {
    "firstName": "{{first_name}}",
    "lastName": "{{last_name}}",
    "phone": "{{phone_number}}",
    "email": "{{email}}"
  }
  ```

Replace the `{{placeholders}}` with the actual field mappings from your trigger step.

::: warning
**Important:** The phone number must include the country code (for example, `+1` for the US or `+31` for the Netherlands). If your lead form collects the phone number without a country code, add a formatting step in your automation to prepend it.
:::


The API response returns the new contact's ID at `data.contactId`. Save that value — you need it for the next step.

> **You can skip the second call.** `POST /v1/contacts` also accepts `listId` (one list) or `listIds` (several) in the create body, which adds the new contact to those lists in the same request. Use the two-step version below only if your automation platform needs the contact to exist before it decides which list to use.

### Configure API Call 2: Add Contact to List

Add a second action step:

- **Method:** `POST`
- **URL:** `https://api.dmchamp.com/v1/contacts/lists?apiKey=YOUR_API_KEY`
- **Headers:**
  ```
  Content-Type: application/json
  ```
- **Body (JSON):**
  ```json
  {
    "contactId": "{{contact_id_from_previous_step}}",
    "listId": "YOUR_LIST_ID"
  }
  ```

Replace `YOUR_LIST_ID` with the actual ID of your contact list (see [Finding Your List ID](#finding-your-list-id) below), and map `contactId` to the `data.contactId` returned by the first API call.

---

## Finding Your List ID

1. In DM Champ, click **Contacts**, then the **Lists** tab.
2. Open the row menu ("⋯") next to the list you want and click **Copy list ID**.

See [Organizing Lists & Contacts](../get-started/list-and-contact-management.md) for the full Lists page walkthrough.

---

## Step 4: Test the Full Workflow

1. Submit another test lead through your Facebook form (or replay the existing test lead in your automation platform).
2. Check DM Champ to confirm:
   - The **contact** was created with the correct name, phone number, and email.
   - The contact was **added to the correct list**.
3. If you have a broadcast, campaign, or AI Agent set to message that list automatically, confirm it triggers as expected.

---

## Data Reference

Below are examples of the data sent and received during the integration.

### Create Contact - Request

```json
POST <span data-t="apiBaseUrl">https://api.dmchamp.com</span>/v1/contacts?apiKey=YOUR_API_KEY

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phone": "+15551234567",
  "email": "jane@example.com"
}
```

### Create Contact - Response

```json
{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}
```

### Add Contact to List - Request

```json
POST <span data-t="apiBaseUrl">https://api.dmchamp.com</span>/v1/contacts/lists?apiKey=YOUR_API_KEY

{
  "contactId": "abc123xyz",
  "listId": "LIST_ID"
}
```

---

## Tips

- **Duplicate handling:** if a contact with the same phone number already exists, the create call returns `{"success": false, "error_code": 409}` and does not return the existing contact. Branch on `error_code` (the HTTP status is 200) and look the contact up with `GET /v1/contacts?phoneNumber=...` before the add-to-list call.
- **Multiple forms:** create separate automation workflows for different lead forms, each targeting a different list and a different broadcast, campaign, or AI Agent.
- **Error notifications:** configure your automation platform to notify you if an API call fails, so you don't lose leads.

---

## Next Steps

- [Moving from Campaigns to Broadcasts & Agents](../moving-from-campaigns.md) — set up something to automatically message new leads.
- [API Access](api-access.md) — full API documentation for advanced integrations.
- [Webhooks](webhooks.md) — get notified when contacts are created or tagged.