> ## Documentation Index
> Fetch the complete documentation index at: https://plai-a079b342.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Dynamic Ad

> This endpoint is used to create a campaign for leads dynamic ads. Lead generation ads are ad campaigns designed to collect contact information (like name, email, phone number) directly from users on Meta platforms without needing them to leave the app.

## Request Body

<ParamField body="userId" type="string" required>
  User ID, If not already created, make a user on [create user
  page](/api-reference/endpoint/auth/create_user) first. If already created,
  retrieve the user ID from [get profile
  page](/api-reference/endpoint/auth/get_profile).
</ParamField>

<ParamField body="campaignName" type="string" required>
  Descriptive name for the campaign
</ParamField>

<ParamField body="status" type="string" default="PAUSED">
  Status of the campaign

  Supported values are: `ACTIVE`, `PAUSED`
</ParamField>

<ParamField body="budget" type="number" required>
  Campaigns daily budget amount.
</ParamField>

<ParamField body="startDate" type="string">
  Start Date Format: `YYYY-MM-DD`, use to schedule the campaign to start at a
  specific date.
</ParamField>

<ParamField body="endDate" type="string">
  End Date Format: `YYYY-MM-DD`, use to schedule the campaign to end at a
  specific date.
</ParamField>

<ParamField body="url" type="string" required>
  Your Website URL
</ParamField>

<ParamField body="specialAdCategories" type="string[]">
  Special ad categories = `HOUSING`, `FINANCIAL_PRODUCTS_SERVICES`,
  `EMPLOYMENT`

  <Note>
    * `HOUSING`: Ads related to property sales, rentals, or home-related
      services. <br />
    * `FINANCIAL_PRODUCTS_SERVICES`: Ads promoting credit cards, loans, insurance,
      or other financial services. <br /> - `EMPLOYMENT`: Ads offering job opportunities
      or recruitment-related services.
  </Note>
</ParamField>

<ParamField body="specialAdCountries" type="string[]">
  <Warning>
    Special Ad Countries is required if specialAdCategories is provided.
  </Warning>

  ISO 3166-1 alpha-2 country codes e.g: `US`,`UK`
</ParamField>

<ParamField body="utmParams" type="string">
  UTM tracking parameters template, expected variables that can be used in it: `{{campaign.id}},{{adset.id}},{{ad.id}},{{campaign.name}},{{adset.name}},{{ad.name}}`
</ParamField>

### Targeting Parameters

<ParamField body="adSetName" type="string">
  Name of the ad set audience
</ParamField>

<ParamField body="gender" type="string">
  <Warning>
    If Special Ad Category is provided, then age targeting will be ignored.
  </Warning>

  Gender targeting , `1` for male, `2` for female, and if you want to target all
  genders skip this parameter
</ParamField>

<ParamField body="ages" type="object">
  <Warning>
    If Special Ad Category is provided, then age targeting will be ignored.
  </Warning>

  <Expandable title="Age Targeting Object">
    <ParamField body="minAge" type="number" required>
      Minimum target age (inclusive)
    </ParamField>

    <ParamField body="maxAge" type="number" required>
      Maximum target age (inclusive)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="locations" type="object[]" required>
  <Warning>
    The locations parameter must include only locations within the country specified in the `specialAdCountries` field. For example, if you set `specialAdCountries` to `US`, then all locations added must be within the United States. Adding locations from other countries will result in an error.
  </Warning>

  <Note>If Audience ID is provided, then location targeting is optional</Note>
  List of areas where you want to show your ads. Get locations data from [here](/api-reference/endpoint/meta/search_targeting_locations)

  <Expandable title="Location Targeting Object">
    <ParamField body="id" type="string" required>
      Facebook location ID
    </ParamField>

    <ParamField body="type" type="string" required>
      Location types: `country`, `region`, `zip`, `country_group`, `neighborhood`, `city`
    </ParamField>

    <ParamField body="distance_unit" type="string">
      <Note>Use Distance Unit when type is `city`</Note>
      Distance unit (`mile` or `km`)
    </ParamField>

    <ParamField body="radius" type="number">
      <Note>Use Radius when type is `city`</Note>
      Radius value
    </ParamField>

    <ParamField body="countryCode" type="string">
      ISO 3166-1 alpha-2 country codes e.g: `US`,`UK`
    </ParamField>

    <ParamField body="countryName" type="string">
      Country Name
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="excludedLocations" type="object[]">
  Areas where you don't want your ads to appear. Get excluded locations data
  from [here](/api-reference/endpoint/meta/search_targeting_locations)

  <Expandable title="Location Targeting Object">
    <ParamField body="id" type="string" required>
      Facebook location ID
    </ParamField>

    <ParamField body="type" type="string" required>
      Location type (city, etc.)
    </ParamField>

    <ParamField body="distance_unit" type="string">
      <Note>Use Distance Unit when type is `city`</Note>
      Distance unit (`mile` or `km`)
    </ParamField>

    <ParamField body="radius" type="number">
      <Note>Use Radius when type is `city`</Note>
      Radius value
    </ParamField>

    <ParamField body="countryCode" type="string">
      ISO 3166-1 alpha-2 country codes e.g: `US`,`UK`
    </ParamField>

    <ParamField body="countryName" type="string">
      Country Name
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="proximityTargeting" type="object[]">
  Targets people within a specific radius of a location. You have to get the
  proximity targeting data on your own.

  <Expandable title="Proximity Targeting Object">
    <ParamField body="countryName" type="string">
      Country Name
    </ParamField>

    <ParamField body="distance_unit" type="string" required>
      Distance Unit, values: `mile`, `kilometer`
    </ParamField>

    <ParamField body="latitude" type="string" required>
      Latitude of the location
    </ParamField>

    <ParamField body="longitude" type="string" required>
      Longitude of the location
    </ParamField>

    <ParamField body="radius" type="number" required>
      Radius value
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="interests" type="object[]">
  Broad audience based on general interests (e.g., fitness, travel). Get interests data from [here](/api-reference/endpoint/meta/search_targeting_interests)

  <Expandable title="Interests Object">
    <ParamField body="id" type="string" required>
      Interest Id
    </ParamField>

    <ParamField body="name" type="string" required>
      Interest Name
    </ParamField>

    <ParamField body="type" type="string" required>
      Interest Type = `interests`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="narrowInterests" type="object[]">
  Refines audience by requiring an additional interest match. Get narrow interests data from [here](/api-reference/endpoint/meta/search_targeting_interests)

  <Expandable title="Narrow Interests Object">
    <ParamField body="id" type="string" required>
      Interest Id
    </ParamField>

    <ParamField body="name" type="string" required>
      Interest Name
    </ParamField>

    <ParamField body="type" type="string" required>
      Interest Type = `interests`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="furtherInterests" type="object[]">
  Adds another layer of filtering—users must match all levels. Get further narrow interests data from [here](/api-reference/endpoint/meta/search_targeting_interests)

  <Expandable title="Further Interests Object">
    <ParamField body="id" type="string" required>
      Interest Id
    </ParamField>

    <ParamField body="name" type="string" required>
      Interest Name
    </ParamField>

    <ParamField body="type" type="string" required>
      Interest Type = `interests`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="targetLocales" type="number[]">
  Use to target specific languages. You can get the list of locales
  [here](/api-reference/endpoint/meta/get_targeting_locales)
</ParamField>

<ParamField body="audienceId" type="string[]">
  Array of audience IDs, you can get the audienceId from list of audiences
  [here](/api-reference/endpoint/meta/get_custom_audiences)
</ParamField>

<ParamField body="excludedAudienceIds" type="string[]">
  Audience IDs to exclude, you can get the audienceId from list of audiences
  [here](/api-reference/endpoint/meta/get_custom_audiences)
</ParamField>

<ParamField body="manualPlacements" type="boolean" default={false}>
  <Note>Set to `false` to use Advantage+ placements (recommended).</Note>

  <Note>
    If you set to `true`, you have to provide `facebook_positions`,
    `instagram_positions`, `messenger_positions`
  </Note>

  Whether placements are manually selected
</ParamField>

<ParamField body="facebook_positions" type="string[]">
  Facebook ad placements = `feed`, `right_hand_column`, `marketplace`,
  `video_feeds`, `story`, `search`, `instream_video`, `facebook_reels`,
  `facebook_reels_overlay`, `profile_feed`, `notification`
</ParamField>

<ParamField body="instagram_positions" type="string[]">
  Instagram ad placements = `stream`, `story`, `explore`, `explore_home`,
  `reels`, `profile_feed`, `ig_search`, `profile_reels`
</ParamField>

<ParamField body="messenger_positions" type="string[]">
  Messenger ad placements = `messenger_home`, `story`
</ParamField>

<ParamField body="userDevices" type="string[]">
  Device targeting, you have to send the device name in string array, you can
  get the list of devices from
  [here](/api-reference/endpoint/meta/get_targeting_systems_lookup)

  <Note>
    Make sure to choose right operating system for the device.

    * for eg. If the user device is iphone, then you have to send `ios` in user operating system.
  </Note>
</ParamField>

<ParamField body="userOS" type="string[]">
  Operating system targeting, you have to send the os platform in string
  array, you can get the list of operating systems from
  [here](/api-reference/endpoint/meta/get_targeting_systems_lookup)
</ParamField>

### Dynamic Ads Parameters

<ParamField body="campaignType" type="string" required>
  For Lead Goal, campaignType is `LEAD_GENERATION`
</ParamField>

<ParamField body="images" type="object[]">
  <Note>
    You can add up to 10 total images and videos in one dynamic ad, atlease 1 image is required if video is not provided.

    * Minimum Image Size: 400x400px
    * Supported Aspect Ratios: 1:1, 16:9, 9:16
  </Note>

  <Expandable title="Image Assets Array">
    <ParamField body="url" type="string" required>
      URL for image asset
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="videos" type="object[]">
  <Note>
    You can add up to 10 total images and videos in one dynamic ad, atlease 1 video is required if image is not provided.
  </Note>

  <Expandable title="Video Assets Array">
    <ParamField body="video_id" type="string" required>
      Facebook video ID, get facebook video id from [here](/api-reference/endpoint/meta/get_ad_account_media)
    </ParamField>

    <ParamField body="thumbnail_url" type="string" required>
      URL for video thumbnail image, get video thumbnail url from [here](/api-reference/endpoint/meta/get_ad_account_media)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="primaryText" type="object[]">
  <Note>
    You can add up to 5 primary text variations, atleast 1 primary text is
    required
  </Note>

  <Expandable title="Primary Text Array">
    <ParamField body="text" type="string" required>
      Main ad copy text
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="headlines" type="object[]">
  <Note>You can include up to 5 headline variations.</Note>

  <Expandable title="Headline Variations Array">
    <ParamField body="text" type="string" required>
      Headline text variation
    </ParamField>
  </Expandable>

  <Warning>
    Headline max length is 255 characters. however, for non-English
    languages, the limit is determined by the number of bytes rather than
    the number of visible characters
  </Warning>
</ParamField>

<ParamField body="leadsFormId" type="string" required>
  Facebook Lead Form ID, get facebook lead form id from
  [here](/api-reference/endpoint/meta/get_leadforms)
</ParamField>

<ParamField body="callToAction" type="string" required>
  Supported call to action types are `LEARN_MORE`, `SIGN_UP`, `DOWNLOAD`,
  `APPLY_NOW`, `SUBSCRIBE`, `GET_QUOTE`, `BOOK_TRAVEL`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates that the HTTP response was successful (status code 200 OK).
</ResponseField>

<ResponseField name="results" type="object">
  <Expandable title="Results Object">
    <ResponseField name="success" type="boolean">
      Indicates whether the specific operation or API action was
      successful.
    </ResponseField>

    <ResponseField name="campaign" type="object">
      <Expandable title="Campaign Object">
        <ResponseField name="leadFormId" type="string">
          The unique identifier for the lead form associated with this
          campaign.
        </ResponseField>

        <ResponseField name="campaignId" type="string">
          The unique identifier for the campaign.
        </ResponseField>

        <ResponseField name="adId" type="string[]">
          Ad IDs Array
        </ResponseField>

        <ResponseField name="adGroupId" type="string">
          The unique identifier for the ad group associated with this
          campaign.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="error" type="string">
      Error string if something went wrong
    </ResponseField>
  </Expandable>
</ResponseField>