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.

JSON Example of the Lead Generation Form entity

{
    "name": "Form name",
    "description": "This is 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.
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.	Yes	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!","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

The above command returns JSON structured like this:

{
  "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!",
        "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 1 - 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!","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

The above command returns JSON structured like this:

{
  "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",
        "privacy_policy_url": "https://www.example.com",
        "description": "Please answer these questions!",
        "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!","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

The above command returns JSON structured like this:

{
  "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",
        "privacy_policy_url": "https://www.example.com",
        "description": "Please answer these questions!",
        "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
            }
          ]
        }
      }
    }
  ]
}

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 1 - Form with a header banner, and three multiple choice questions.​

Example 2 - Form with no header banner and two consent fields.​

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 1 - Form with a header banner, and three multiple choice questions.

Example 2 - Form with no header banner and two consent fields.