Lead Generation Ads Guide

Lead generation ads allow you to present the user with a form when they interact with the ad.

Lead Generation Forms

A lead_generation_form entity contains the properties of each form, and a creative entity for a lead ad has a reference to this form through the field lead_generation_form_id.

{
    "name": "Form name",
    "description": "This is the description of my lead gen form",
    "title": "My Lead Gen Form",
    "form_fields": [
        {
            "type": "FIRST_NAME",
        },
        {
            "type": "LAST_NAME",
        },
        {
            "type": "EMAIL",
        },
        {
            "type": "CUSTOM",
            "custom_form_field_properties": {
                "type": "TEXT",
                "description": "What is your favorite color?"
            }
        },
        {
            "type": "CUSTOM",
            "custom_form_field_properties": {
                "type": "MULTIPLE_CHOICE_SINGLE_SELECTION",
                "description": "Do you rent or own??"
                "multiple_choice_options": [
                    {
                        "choice_description": "Own"
                    },
                    {
                        "choice_description": "Rent"
                    }
                ]
            }
        }
    ],
    "privacy_policy_url": "https://www.example.com/",
    "legal_disclosures": {
        "title": "My terms",
        "description": "These are my terms",
        "consent_form_fields": [
            {
                "consent_description": "I agree to the terms",
                "required": true
            }
        ]
    },
    "banner_media_id": "a0bc123d-d4ab-4ecc-b4eb-1a23bc4567d2"
}

Attribute	Description	Required	Possible Values
name	Lead generation form name.	Yes	A text string.
description	A description of the lead generation form. This appears on the form before its question fields.	Yes	A text string. Max length is 180 characters.
title	The title of the lead generation form. This appears on the form before its question fields.	Yes	A text string. Max length is 25 characters.
form_fields	A list of the questions in the form.	Yes (See Form Requirements below.)	A list of JSON objects that represent the questions in the form. Each element of the list must be a JSON object that contains a `type` attributed. For example: `{"type": "COMPANY_NAME"}` Possible values for `type`: `FIRST_NAME`, `LAST_NAME`, `EMAIL`, `PHONE_NUMBER`, `ADDRESS`, `POSTAL_CODE`, `BIRTHDAY_DATE`, `JOB_TITLE`, `COMPANY_NAME`, `CUSTOM`. If `type` is `CUSTOM`, the object must also include the `custom_form_field_properties` property.
privacy_policy_url	URL that points to your brand's Privacy Policy. A link to this page will appear on the confirmation screen before the user submits their entries.	No	A URL string. For example: `"https://www.example.com"`
legal_disclosures	An object that describes that legal disclosures in the form.	No	A Legal Disclosure Properties object that contains information about the legal disclosures in the form.
banner_media_id	Media ID of the form's banner image.	No	A text string that contains a media ID. Minimum Image Size: 750x230 Maximum Image Size: 1875x575 Aspect Ratio: 75:23 Max File Size: 5 MB
end_page_properties	End page properties which show after form submission.	No	An End Page Properties object that contains information about the end page properties of the form.

Custom Form Field Properties

Attribute	Description	Required	Possible Values
type	Type of the form field.	Yes	`TEXT`, `DATE`, `MULTIPLE_CHOICE_SINGLE_SELECTION`, `MULTIPLE_CHOICE_MULTI_SELECTION`
description	Description of the question being asked	Yes	A text string.
multiple_choice_options	List of multiple choice options available for users to answer.	Yes if type is `MULTIPLE_CHOICE_SINGLE_SELECTION` or `MULTIPLE_CHOICE_MULTI_SELECTION`	A list of JSON objects that represent multiple choices available for a user to answer the question. Each element of the list is an object that contains the required string `choice_description` (examples can be seen below). Elements in the list can also be marked as preferred by adding the optional `option_preferred_status` field. Learn more about Preferred options in the section below.

Multiple Choice Option Example

By default, multiple choice options can be represented with just a choice_description as shown below:

{
  "multiple_choice_options": [
    {
      "choice_description": "Red"
    },
    {
      "choice_description": "Green"
    },
    {
      "choice_description": "Blue"
    }
  ]
}

Preferred Choice Options

NOTE: Only one question per form can use preferred options.

Multiple choice questions (of type MULTIPLE_CHOICE_SINGLE_SELECTION) can mark one or more options as being preferred. To do so, all options in that question need to be marked as either PREFERRED or NOT_PREFERRED using the option_preferred_status field. Questions using the field need to have a minimum of one PREFERRED and one NOT_PREFERRED option.

{
  "multiple_choice_options": [
    {
      "choice_description": "Red",
      "option_preferred_status": "NOT_PREFERRED"
    },
    {
      "choice_description": "Blue",
      "option_preferred_status": "NOT_PREFERRED"
    },
    {
      "choice_description": "Green",
      "option_preferred_status": "PREFERRED"
    }
  ]
}

Legal Disclosure Properties

Attribute	Description	Required	Possible Values
title	Title of the legal disclosure.	Yes	A text string. For example: "Terms of Service". Max length is 35 characters.
description	A description of the terms that the user must agree to.	Yes	A text string. Max length is 80 characters.
consent_form_fields	Description of the consent needed and if it is required.	No	A list of JSON objects that represent consents that must be given by the user when submitting the form. Each element of the list is a simple object that contains a text string `consent_description` and a boolean property `required`: `{"consent_description": "I agree to the terms", "required": true }` Can contain up to two elements.

End Page Properties

Attribute	Description	Required	Possible Values
call_to_action	The call-to-action button copy to show to the user.	Yes	VIEW_WEBSITE, BOOK_NOW, LEARN_MORE, DONATE, SPECIAL_OFFER, SCHEDULE_NOW, BUY_TICKETS, TEST_DRIVE, APPLY_NOW, GET_COUPON, CLAIM_SAMPLE, FREE_TRIAL
url	URL of site to show when the call-to-action button is clicked.	Yes	Any valid URL.

Form Requirements

FIRST_NAME and LAST_NAME fields must be included
At least one of the EMAIL field or the PHONE_NUMBER field must be included.
The ADDRESS and POSTAL_CODE fields cannot both be included in the same form.

How to create a Lead Generation Ad

Creating a Lead Generation Ad consists of the following steps:

Create a header banner image for your form. (Only required if the form contains a banner header)
Create a Lead Generation Form entity.
Create a Creative entity using the lead_generation_form_id from step 2.
Use the creative created in step 3 to create a Lead Generation ad.

Use the Create Media endpoint to create a media object for your banner's header image. Refer to the Media entity documentation for more details.

Banner images must have a minimum size of 750x230, a maximum size of 1875x575, and a 75:23 aspect ratio. The max file size for a banner image is 5 MB.

Creating a Lead Generation Form

curl -X POST \
  -d '{"lead_generation_forms":[{"privacy_policy_url":"https://www.example.com","name":"My Lead Gen Form","description":"Please answer these questions!","title": "Sample Form","form_fields":[{"type":"FIRST_NAME"},{"type":"LAST_NAME"},{"type":"PHONE_NUMBER"},{"type":"ADDRESS"},{"type":"BIRTHDAY_DATE"},{"type":"JOB_TITLE"},{"type":"COMPANY_NAME"},{"type":"CUSTOM","custom_form_field_properties":{"type":"TEXT","description":"What is your favorite word?"}},{"type":"CUSTOM","custom_form_field_properties":{"type":"MULTIPLE_CHOICE_MULTI_SELECTION","description":"What is your favorite color?","multiple_choice_options":[{"choice_description":"Red"},{"choice_description":"Blue"},{"choice_description":"Green"}]}}],"legal_disclosures":{"title":"legal title","description":"legal description","consent_form_fields":[{"consent_description":"Do you consent to the terms?","required":true}]},"banner_media_id":"d5cf309c-d4ab-4ecc-b4eb-3u63ba3314c2"}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/lead_generation_forms

{
  "request_status": "SUCCESS",
  "request_id": "3f45ba66-a70a-4528-80fc-7ade7baf6473",
  "lead_generation_forms": [
    {
      "sub_request_status": "SUCCESS",
      "lead_generation_form": {
        "id": "9e91fbc4-7cc3-4cd0-ad11-c40c94859091",
        "updated_at": "2024-10-22T17:16:52.167Z",
        "created_at": "2024-10-22T17:16:52.167Z",
        "name": "My Lead Gen Form",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "privacy_policy_url": "https://www.example.com",
        "description": "Please answer these questions!",
        "title": "Sample Form",
        "form_fields": [
          {
            "type": "FIRST_NAME",
            "is_required": true
          },
          {
            "type": "LAST_NAME",
            "is_required": true
          },
          {
            "type": "PHONE_NUMBER",
            "is_required": true
          },
          {
            "type": "ADDRESS",
            "is_required": true
          },
          {
            "type": "BIRTHDAY_DATE",
            "is_required": true
          },
          {
            "type": "JOB_TITLE",
            "is_required": true
          },
          {
            "type": "COMPANY_NAME",
            "is_required": true
          },
          {
            "type": "CUSTOM",
            "is_required": true,
            "custom_form_field_properties": {
              "type": "TEXT",
              "description": "What is your favorite word?"
            }
          },
          {
            "type": "CUSTOM",
            "is_required": true,
            "custom_form_field_properties": {
              "type": "MULTIPLE_CHOICE_MULTI_SELECTION",
              "description": "What is your favorite color?",
              "multiple_choice_options": [
                {
                  "choice_description": "Red"
                },
                {
                  "choice_description": "Blue"
                },
                {
                  "choice_description": "Green"
                }
              ]
            }
          }
        ],
        "legal_disclosures": {
          "title": "legal title",
          "description": "legal description",
          "consent_form_fields": [
            {
              "consent_description": "Do you consent to the terms?",
              "required": true
            }
          ]
        },
        "banner_media_id": "d5cf309c-d4ab-4ecc-b4eb-3u63ba3314c2"
      }
    }
  ]
}

Creating a Lead Generation Creative using a lead generation form

curl -X POST \
  -d '{"creatives":[{"ad_account_id":"8adc3db7-8148-4fbf-999c-8d2266369d74","name":"My Lead Gen Creative","type":"LEAD_GENERATION","headline":"This is my headline","brand_name":"Great brand","shareable":true,"call_to_action":"SIGN_UP","top_snap_media_id":"3m08b7ea-2dc6-4854-a44f-b3am70665b32","profile_properties":{"profile_id":"2e44b569-0632-4cf1-a4ac-116544681eb2"},"lead_generation_form_id":"9e91fbc4-7cc3-4cd0-ad11-c40c94859091"}]}'
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives

Creating a Lead Generation Ad using a creative

curl -X POST \
  -d '{"ads":[{"ad_squad_id":"123456bd-8300-45f9-b335-9a3592b5f95c","creative_id":"35fce3af-e1c7-46d4-a075-79180a3073ef","name":"My Lead Generation Ad","type":"LEAD_GENERATION","status":"ACTIVE"}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adsquads/123456bd-8300-45f9-b335-9a3592b5f95c/ads

{
  "request_status": "SUCCESS",
  "request_id": "61f48d3000ff091ecf5f32b8c10001737e616473617069736300016275696c642d61353730363532632d312d3531322d3000010125",
  "ads": [
    {
      "sub_request_status": "SUCCESS",
      "ad": {
        "id": "52328535-5947-4213-a8c0-da47d144f5ec",
        "effective_status": "ACTIVE",
        "name": "My Lead Generation Ad",
        "ad_squad_id": "123456bd-8300-45f9-b335-9a3592b5f95c",
        "creative_id": "35fce3af-e1c7-46d4-a075-79180a3073ef",
        "status": "ACTIVE",
        "type": "LEAD_GENERATION",
        "render_type": "STATIC",
        "review_status": "PENDING",
        "review_status_reasons": [],
        "review_rejection_ids": [],
        "approval_type": "NONE",
        "conditional_approval_reason_ids": [],
        "conditional_approval_reason_texts": [],
        "delivery_status": [
          "INVALID_PENDING_REVIEW_STATUS",
          "INVALID_EFFECTIVE_INVALID"
        ]
      }
    }
  ]
}

For Lead Generation Ads, type property must be set to LEAD_GENERATION.

Example - Create a form with a header banner, and three multiple choice questions.

curl -X POST \
  -d '{"lead_generation_forms":[{"name":"Form with lots of information","privacy_policy_url":"https://www.example.com","description":"Please answer these questions!","title": "Sample Form","form_fields":[{"type":"FIRST_NAME"},{"type":"LAST_NAME"},{"type":"EMAIL"},{"type":"CUSTOM","custom_form_field_properties":{"type":"MULTIPLE_CHOICE_SINGLE_SELECTION","description":"What is your age range?","multiple_choice_options":[{"choice_description":"0-14"},{"choice_description":"15-25"},{"choice_description":"25-50"},{"choice_description":"Over 50"}]}},{"type":"CUSTOM","custom_form_field_properties":{"type":"MULTIPLE_CHOICE_MULTI_SELECTION","description":"Which of these foods do you like?","multiple_choice_options":[{"choice_description":"Hamburgers"},{"choice_description":"Pizza"},{"choice_description":"Salad"},{"choice_description":"Steak"}]}},{"type":"CUSTOM","custom_form_field_properties":{"type":"TEXT","description":"What is your favorite movie?"}}],"banner_media_id":"d5cf309c-d4ab-4ecc-b4eb-3u63ba3314c2"}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/lead_generation_forms

{
  "request_status": "SUCCESS",
  "request_id": "3922cb1e-4435-46cf-9387-3e3a4b469cd9",
  "lead_generation_forms": [
    {
      "sub_request_status": "SUCCESS",
      "lead_generation_form": {
        "id": "35fce3af-e1c7-46d4-a075-79180a3073ef",
        "updated_at": "2024-10-22T17:49:27.727Z",
        "created_at": "2024-10-22T17:49:27.727Z",
        "name": "Form with lots of information",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "description": "Please answer these questions!",
        "title": "Sample Form",
        "form_fields": [
          {
            "type": "FIRST_NAME",
            "is_required": true
          },
          {
            "type": "LAST_NAME",
            "is_required": true
          },
          {
            "type": "EMAIL",
            "is_required": true
          },
          {
            "type": "CUSTOM",
            "is_required": true,
            "custom_form_field_properties": {
              "type": "MULTIPLE_CHOICE_SINGLE_SELECTION",
              "description": "What is your age range?",
              "multiple_choice_options": [
                {
                  "choice_description": "0-14"
                },
                {
                  "choice_description": "15-25"
                },
                {
                  "choice_description": "25-50"
                },
                {
                  "choice_description": "Over 50"
                }
              ]
            }
          },
          {
            "type": "CUSTOM",
            "is_required": true,
            "custom_form_field_properties": {
              "type": "MULTIPLE_CHOICE_MULTI_SELECTION",
              "description": "Which of these foods do you like?",
              "multiple_choice_options": [
                {
                  "choice_description": "Hamburgers"
                },
                {
                  "choice_description": "Pizza"
                },
                {
                  "choice_description": "Salad"
                },
                {
                  "choice_description": "Steak"
                }
              ]
            }
          },
          {
            "type": "CUSTOM",
            "is_required": true,
            "custom_form_field_properties": {
              "type": "TEXT",
              "description": "What is your favorite movie?"
            }
          }
        ],
        "banner_media_id": "d5cf309c-d4ab-4ecc-b4eb-3u63ba3314c2"
      }
    }
  ]
}

curl -X POST \
  -d '{"lead_generation_forms":[{"name":"Form with consent","privacy_policy_url":"https://www.example.com","description":"Please answer these questions!","title": "Sample Form","form_fields":[{"type":"FIRST_NAME"},{"type":"LAST_NAME"},{"type":"PHONE_NUMBER"}],"legal_disclosures":{"title":"Legal Terms","description":"These are our terms","consent_form_fields":[{"consent_description":"I read your terms","required":true},{"consent_description":"I agree to your terms","required":true}]}} ]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/lead_generation_forms

{
  "request_status": "SUCCESS",
  "request_id": "61f9cbe000ff06c274effe15af0001737e616473617069736300016275696c642d37353461666336622d312d3531332d3000010135",
  "creatives": [
    {
      "sub_request_status": "SUCCESS",
      "creative": {
        "id": "35fce3af-e1c7-46d4-a075-79180a3073ef",
        "updated_at": "2024-10-22T17:55:40.928Z",
        "created_at": "2024-10-22T17:55:40.928Z",
        "name": "Form with consent",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "LEAD_GENERATION",
        "description": "Please answer these questions!",
        "title": "Sample Form",
        "form_fields": [
          {
            "type": "FIRST_NAME",
            "is_required": true
          },
          {
            "type": "LAST_NAME",
            "is_required": true
          },
          {
            "type": "PHONE_NUMBER",
            "is_required": true
          }
        ],
        "legal_disclosures": {
          "title": "Legal Terms",
          "description": "These are our terms",
          "consent_form_fields": [
            {
              "consent_description": "I read your terms",
              "required": true
            },
            {
              "consent_description": "I agree to your terms",
              "required": true
            }
          ]
        }
      }
    }
  ]
}

Get Lead Generation Form using Lead Generation Id

This endpoint retrieves lead generation form using the lead_generation_form_id.

HTTP Request

GET https://adsapi.snapchat.com/v1/lead_generation_forms/{lead_generation_form_id}

URL Parameters

Parameter	Description
lead_generation_form_id	The ID of the Lead generation Form

Example - Get Lead Generation Form using Lead Generation Id

curl "https://adsapi.snapchat.com/v1/lead_generation_forms/{lead_generation_form_id}" \
  -H "Authorization: Bearer meowmeowmeow"

{
  "request_status": "SUCCESS",
  "request_id": "test-req-id-1234-abcd-5678-efgh",
  "lead_generation_forms": [
    {
      "sub_request_status": "SUCCESS",
      "lead_generation_form": {
        "id": "test-form-id-abcd-1234-efgh-5678",
        "updated_at": "2024-07-22T10:00:00.000Z",
        "created_at": "2023-01-15T09:30:00.000Z",
        "name": "Generic Mock Form 2023-01-15",
        "ad_account_id": "test-ad-id-aaaa-bbbb-cccc-dddd",
        "privacy_policy_url": "https://www.example.com/privacy",
        "description": "This is a placeholder description for a test form.",
        "title": "Test Form",
        "form_fields": [
          {
            "type": "FIRST_NAME"
          },
          {
            "type": "LAST_NAME"
          },
          {
            "type": "EMAIL"
          }
        ],
        "legal_disclosures": {
          "title": "Standard Terms and Conditions",
          "description": "By submitting this form, I confirm I am 18+ and agree to the <a href=\"https://www.example.com/terms\">Terms of Use</a> and <a href=\"https://www.example.com/rules\">Official Contest Rules</a> and to receive marketing communications. I have read and acknowledged the <a href=\"https://www.example.com/privacy\">Privacy Policy</a>."
        },
        "strategy_type": "MORE_VOLUME"
      }
    }
  ]
}

Get Lead Generation Forms under an Ad Account

This endpoint retrieves lead generation forms under an Ad Account.

HTTP Request

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/lead_generation_forms

URL Parameters

Parameter	Description
ad_account_id	The ID of the Ad Account

Example - Get Lead Generation Forms under an Ad Account

curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/lead_generation_forms" \
  -H "Authorization: Bearer meowmeowmeow"

{
  "request_status": "SUCCESS",
  "request_id": "test-req-id-1111-2222-3333-4444",
  "paging": {},
  "lead_generation_forms": [
    {
      "sub_request_status": "SUCCESS",
      "lead_generation_form": {
        "id": "test-form-id-aaaa-bbbb-cccc-dddd",
        "updated_at": "2024-07-22T10:00:00.000Z",
        "created_at": "2023-01-15T09:30:00.000Z",
        "name": "Test Form One created on 2023-01-15",
        "ad_account_id": "test-ad-id-xxxx-yyyy-zzzz-wwww",
        "privacy_policy_url": "https://www.test-site.com/privacy",
        "description": "This is a test description for form number one.",
        "title": "Form Number One",
        "form_fields": [
          {
            "type": "FIRST_NAME"
          },
          {
            "type": "LAST_NAME"
          },
          {
            "type": "EMAIL"
          }
        ],
        "legal_disclosures": {
          "title": "Standard Test Terms and Conditions",
          "description": "By submitting this test form, I confirm I am 18+ and agree to the <a href=\"https://www.test-site.com/terms\">Terms of Use</a> and <a href=\"https://www.test-site.com/rules\">Official Test Rules</a> and to receive marketing communications from TestBrand. I have read and acknowledged the <a href=\"https://www.test-site.com/privacy\">Test Privacy Policy</a>."
        },
        "strategy_type": "MORE_VOLUME"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "lead_generation_form": {
        "id": "test-form-id-eeee-ffff-gggg-hhhh",
        "updated_at": "2024-07-20T15:30:00.000Z",
        "created_at": "2022-03-10T11:00:00.000Z",
        "name": "Test Form Two created on 2022-03-10",
        "ad_account_id": "test-ad-id-xxxx-yyyy-zzzz-wwww",
        "privacy_policy_url": "https://www.test-company.com/privacy",
        "description": "Complete this test survey for a chance to win.",
        "title": "Test Survey",
        "form_fields": [
          {
            "type": "FIRST_NAME"
          },
          {
            "type": "LAST_NAME"
          },
          {
            "type": "EMAIL"
          },
          {
            "type": "JOB_TITLE"
          },
          {
            "type": "BIRTHDAY_DATE"
          },
          {
            "type": "COMPANY_NAME"
          },
          {
            "type": "PHONE_NUMBER"
          },
          {
            "type": "POSTAL_CODE"
          },
          {
            "type": "CUSTOM",
            "custom_form_field_properties": {
              "type": "TEXT",
              "description": "How often do you use test products?"
            }
          },
          {
            "type": "CUSTOM",
            "custom_form_field_properties": {
              "type": "MULTIPLE_CHOICE_MULTI_SELECTION",
              "description": "Test product preference?",
              "multiple_choice_descriptions": [
                "Option A",
                "Option B",
                "Option C",
                "All of the above!"
              ],
              "multiple_choice_options": [
                {
                  "choice_description": "Option A"
                },
                {
                  "choice_description": "Option B"
                },
                {
                  "choice_description": "Option C"
                },
                {
                  "choice_description": "All of the above!"
                }
              ]
            }
          }
        ],
        "legal_disclosures": {
          "title": "Test Company Legal Terms",
          "description": "https://www.test-company.com/legal/terms-of-service"
        },
        "banner_media_id": "test-banner-id-1b1b-2c2c-3d3d-4e4e",
        "strategy_type": "MORE_VOLUME"
      }
    }
  ]
}

Webhook Integrations

Webhook integrations allow you to receive lead data in real-time as users submit leads through Snap's lead generation forms. Only one webhook integration can be created per form.

Attributes

Fields that are marked as Always Present are included with all webhooks. Other fields may or may not appear in webhooks depending on how the advertiser set up the form.

Field	Type	Always Present?
form_id	String	YES
form_name	String	YES
ad_account_id	String	YES
campaign_id	String	YES
campaign_name	String	YES
ad_id	String	YES
ad_name	String	YES
ad_squad_id	String	YES
lead_id	String	YES
ad_squad_name	String	YES
create_time	String (Millisecond UNIX timestamp)	YES
first_name	String	NO
last_name	String	NO
email	String	NO
phone_number	String	NO
postal_code	String	NO
address_line_1	String	NO
address_line_2	String	NO
address_level_1	String	NO
address_level_2	String	NO
birthday	String	NO
job_title	String	NO
company_name	String	NO
custom_field_1	String	NO
custom_field_2	String	NO
custom_field_3	String	NO
custom_field_4	String	NO
custom_field_5	String	NO
custom_field_6	String	NO
custom_field_7	String	NO
custom_field_8	String	NO
consent_1	String	NO
consent_2	String	NO

Example Webhook Payload

{
  "last_name": "Doe",
  "ad_squad_id": "886bed67-548a-41ce-bb25-2704c32fcb92",
  "ad_account_id": "8afdf490-bec6-4963-8fdb-b445c32fcb89",
  "ad_id": "b387c801-0803-4fd4-861c-fabb4dfc3eef",
  "phone_number": "5555555555",
  "first_name": "John",
  "lead_id": "6ed7a5e5-d6db-4aa4-b141-e0def7bce05c",
  "campaign_id": "134d637c-cb54-4395-8f1d-12c5de1c67d1",
  "create_time": "1715990163718",
  "form_id": "21d3409e-8ae4-4417-9a89-9208f6c17bea",
  "form_name": "Test Form",
  "ad_name": "Test Ad",
  "ad_squad_name": "Test Ad Squad",
  "campaign_name": "Test Campaign"
}

Create a new Webhook Integration

Creates a webhook integration tied to a lead generation form. While the integration is active, Snap will send a webhook for every lead that is submitted through the specified form. With the webhook integration, Snap will also provide an HMAC secret that could be used to verify the authenticity of the webhook events.

HTTP Request

POST /v1/lead_gen/integrations/public_webhook

Body Parameters

Parameter	Description
form_id	ID of the form you would like to set up an integration with.
webhook_url	The URL to which Snap will send webhook events whenever a lead is received.

Example - Create a new Webhook Integration

curl -X POST \
  -d '{"webhook_integrations":[{"form_id":"d3b752b7-2937-4632-a38a-fb30c2c6a23a","webhook_url":"https://www.test.com"}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/lead_gen/integrations/public_webhook

{
  "requestId": "22a099ea-cae0-4e0b-8047-c642cdb61f5e",
  "requestStatus": "200",
  "webhookIntegrations": [
    {
      "subRequestStatus": "200",
      "webhookIntegration": {
        "formId": "d3b752b7-2937-4632-a38a-fb30c2c6a23a",
        "adAccountId": "2eab7f21-1496-4ea1-a66d-f54658c86cb0",
        "webhookUrl": "https://www.test.com",
        "integrationId": "26ed0a8c-27fd-4d28-aec7-9d21bcd0fae1",
        "partnerType": "PUBLIC_WEBHOOK",
        "hmacSecret": "47941324-5cae-4344-ac10-6f7a9aa93c80"
      }
    }
  ]
}

Send Test Lead Data

This endpoint triggers sample / dummy data (see example) to be sent to the webhook URL associated with that integration as a way of running a quick end-to-end test.

HTTP Request

GET /v1/lead_gen/integrations/{integration_id}/test

URL Parameters

Parameter	Description
integration_id	ID of the webhook integration for which you would like to retrieve test data.

Example - Send Test Lead Data

curl "https://adsapi.snapchat.com/v1/lead_gen/integrations/{integration_id}/test" \
  -H "Authorization: Bearer meowmeowmeow"

{
  "request_id": "1077db71-7648-493c-aaa4-79545a30c050",
  "request_status": "200"
}

Dummy Data sent with Test Event

For every request made to the /test endpoint, the following form data gets sent, regardless whether the form details match your current form:

{
  "form_id": "02705624-4602-4474-8705-706385f3f2de",
  "form_name": "Snap Lead Generation Form",
  "ad_account_id": "80b0230c-b1cd-410c-bf1f-3eecf5060426",
  "campaign_id": "765ac990-085b-4f26-bf81-5c37864cdeb1",
  "campaign_name": "Snap Test Campaign Name",
  "ad_id": "fb226924-c26e-4105-b5a2-7348dd326629",
  "ad_name": "Snap Test Ad",
  "ad_squad_id": "d5a0b61d-2c35-4b89-98e9-5626731d421c",
  "ad_squad_name": "Snap Test Ad Squad Name",
  "lead_id": "13cbb197-9274-401d-aa87-0482bad1a307",
  "create_time": "2025-06-23T12:55:39.638Z",
  "first_name": "Sample Lead First Name",
  "last_name": "Sample Lead Last Name",
  "email": "johndoe@snapchat.com",
  "phone_number": "555-123-4567"
}

Get All Webhook Integrations under a Form

Fetch the list of all integrations for a certain partner type linked to the given form ID.

HTTP Request

GET /v1/lead_gen/forms/{form_id}/integrations?partner_type=PUBLIC_WEBHOOK

URL Parameters

Parameter	Description
form_id	ID of the form you are querying for integrations.
partner_type	Type of webhook integrations. Should be set to `PUBLIC_WEBHOOK`

Example - Get All Webhook Integrations under a Form

curl "https://adsapi.snapchat.com/v1/lead_gen/forms/{form_id}/integrations?partner_type=PUBLIC_WEBHOOK" \
  -H "Authorization: Bearer meowmeowmeow"

{
  "requestId": "d849e937-5dc6-45a8-a2ea-3b41448dcd6b",
  "requestStatus": "200",
  "partnerIntegrations": [
    {
      "integrationId": "e8351e8d-3c39-42f7-9f65-cf3cc0a55067",
      "adAccountId": "2eab7f21-1496-4ea1-a66d-f54658c86cb0",
      "connectionId": "a6b9a201-519d-454d-94f2-099dbe934edc",
      "partnerType": "PUBLIC_WEBHOOK",
      "genericWebhookHandlerInfo": {
        "webhookUrl": "https://www.snapchat.com/test"
      }
    }
  ]
}

Delete a Webhook Integration

Deletes a specified webhook integration. When deleted, Snap will stop sending webhook events for the associated form integration. To add another webhook integration, call the create a webhook integration endpoint again.

HTTP Request

DELETE /v1/lead_gen/integrations/{integration_id}

URL Parameters

Parameter	Description
integration_id	ID of the webhook integration you would like to delete.

Example - Delete a Webhook Integration

curl -X DELETE \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/lead_gen/integrations/{integration_id}

{
  "request_status": "SUCCESS",
  "request_id": "6f0f1a56-3eda-4474-8d50-05edd2ce2c36"
}

Optional Message Authentication

When you create a public webhook integration, the response will carry an hmacSecret value which you can use to verify that a webhook event came from Snap. Webhooks contain a Signature header that you can validate against, this secret will be same for all integrations under same ad account.

You can perform this validation by following the steps below to generate a signature and then ensure that it matches the contents of the webhook's Signature header.

Generating and Validating the Signature

Step 1

Generate the signing message by concatenating the following:

The timestamp found in the t header response of your webhook event.
The character . (A delimiter).
The webhook's JSON request body, encoded in UTF-8.

Step 2

Compute an HMAC with the SHA256 hash function. Use the hmacSecret you received from Snap when creating the webhook integration, and the message generated in Step 1.

Step 3

Compare the signature generated in Step 2 with the contents of the webhook's Signature header. If they match, you have validated that the webhook came from Snap.

Example code for generating the signature

The example below tests the signature generation process in Go, using arabic and special characters in the JSON body.

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
)

// calculateSignature computes an HMAC-SHA256 signature and returns
// it as a hexadecimal string.
// Parameters:
//   - timestamp: The value passed with the event's timestamp header
//   - body: The request body (JSON string)
//   - secretKey: The key used for HMAC signature generation
func calculateSignature(timestamp, body, secretKey string) string {
	message := timestamp + "." + body
	mac := hmac.New(sha256.New, []byte(secretKey))
	mac.Write([]byte(message))
	return hex.EncodeToString(mac.Sum(nil))
}

func main() {
	// Fetch values from the lead event payload and header
	rawBody := `{"form_id":"46c41f3b","first_name":"ييصضي
"}`
	headerTimestamp := "1740506902"
	secretKey := "6fc9e887acb44f178faa06a1a43a8454"
	// test the calculation
	signature := calculateSignature(headerTimestamp, rawBody, secretKey)
	expectedSignature := "47efe078988036ad84dc7061f2a8a102d45dc0a17b9f8188dba9b4c86c55c64b"
	fmt.Printf("Computed:  %s\n", signature)
	fmt.Printf("Expected:  %s\n", expectedSignature)
	if signature == expectedSignature {
		fmt.Println("✓ Signatures match")
	} else {
		fmt.Println("✗ Signatures do not match")
	}
}

Was this page helpful?

Yes

Lead Generation Forms​

Custom Form Field Properties​

Multiple Choice Option Example​

Preferred Choice Options​

Legal Disclosure Properties​

End Page Properties​

Form Requirements​

How to create a Lead Generation Ad​

Creating a header banner image for your form​

Creating a Lead Generation Form​

Creating a Lead Generation Creative using a lead generation form​

Creating a Lead Generation Ad using a creative​

Example - Create a form with a header banner, and three multiple choice questions.​

Example - Create a form with no header banner and two consent fields.​

Get Lead Generation Form using Lead Generation Id​

HTTP Request​

URL Parameters​

Example - Get Lead Generation Form using Lead Generation Id​

Get Lead Generation Forms under an Ad Account​

HTTP Request​

URL Parameters​

Example - Get Lead Generation Forms under an Ad Account​

Webhook Integrations​

Attributes​

Create a new Webhook Integration​

HTTP Request​

Body Parameters​

Example - Create a new Webhook Integration​

Send Test Lead Data​

HTTP Request​

URL Parameters​

Example - Send Test Lead Data​

Dummy Data sent with Test Event​

Get All Webhook Integrations under a Form​

HTTP Request​

URL Parameters​

Example - Get All Webhook Integrations under a Form​

Delete a Webhook Integration​

HTTP Request​

URL Parameters​

Example - Delete a Webhook Integration​

Optional Message Authentication​

Generating and Validating the Signature​

Example code for generating the signature​

Lead Generation Forms

Custom Form Field Properties

Multiple Choice Option Example

Preferred Choice Options

Legal Disclosure Properties

End Page Properties

Form Requirements

How to create a Lead Generation Ad

Creating a header banner image for your form

Creating a Lead Generation Form

Creating a Lead Generation Creative using a lead generation form

Creating a Lead Generation Ad using a creative

Example - Create a form with a header banner, and three multiple choice questions.

Example - Create a form with no header banner and two consent fields.

Get Lead Generation Form using Lead Generation Id

HTTP Request

URL Parameters

Example - Get Lead Generation Form using Lead Generation Id

Get Lead Generation Forms under an Ad Account

HTTP Request

URL Parameters

Example - Get Lead Generation Forms under an Ad Account

Webhook Integrations

Attributes

Create a new Webhook Integration

HTTP Request

Body Parameters

Example - Create a new Webhook Integration

Send Test Lead Data

HTTP Request

URL Parameters

Example - Send Test Lead Data

Dummy Data sent with Test Event

Get All Webhook Integrations under a Form

HTTP Request

URL Parameters

Example - Get All Webhook Integrations under a Form

Delete a Webhook Integration

HTTP Request

URL Parameters

Example - Delete a Webhook Integration

Optional Message Authentication

Generating and Validating the Signature

Example code for generating the signature