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.

Dynamic Ad

cURL

curl --request POST \
  --url https://public.plai.io/meta/create_campaign \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "userId": "<string>",
  "campaignName": "<string>",
  "status": "<string>",
  "budget": 123,
  "startDate": "<string>",
  "endDate": "<string>",
  "url": "<string>",
  "specialAdCategories": [
    "<string>"
  ],
  "specialAdCountries": [
    "<string>"
  ],
  "utmParams": "<string>",
  "adSetName": "<string>",
  "gender": "<string>",
  "ages": {
    "minAge": 123,
    "maxAge": 123
  },
  "locations": [
    {
      "id": "<string>",
      "type": "<string>",
      "distance_unit": "<string>",
      "radius": 123,
      "countryCode": "<string>",
      "countryName": "<string>"
    }
  ],
  "excludedLocations": [
    {
      "id": "<string>",
      "type": "<string>",
      "distance_unit": "<string>",
      "radius": 123,
      "countryCode": "<string>",
      "countryName": "<string>"
    }
  ],
  "proximityTargeting": [
    {
      "countryName": "<string>",
      "distance_unit": "<string>",
      "latitude": "<string>",
      "longitude": "<string>",
      "radius": 123
    }
  ],
  "interests": [
    {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>"
    }
  ],
  "narrowInterests": [
    {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>"
    }
  ],
  "furtherInterests": [
    {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>"
    }
  ],
  "targetLocales": [
    123
  ],
  "audienceId": [
    "<string>"
  ],
  "excludedAudienceIds": [
    "<string>"
  ],
  "manualPlacements": true,
  "facebook_positions": [
    "<string>"
  ],
  "instagram_positions": [
    "<string>"
  ],
  "messenger_positions": [
    "<string>"
  ],
  "userDevices": [
    "<string>"
  ],
  "userOS": [
    "<string>"
  ],
  "campaignType": "<string>",
  "images": [
    {
      "url": "<string>"
    }
  ],
  "videos": [
    {
      "video_id": "<string>",
      "thumbnail_url": "<string>"
    }
  ],
  "primaryText": [
    {
      "text": "<string>"
    }
  ],
  "headlines": [
    {
      "text": "<string>"
    }
  ],
  "leadsFormId": "<string>",
  "callToAction": "<string>"
}
'

200

{
  "success": true,
  "results": {
    "success": true,
    "campaign": {
      "leadFormId": "<string>",
      "campaignId": "<string>",
      "adId": [
        "<string>"
      ],
      "adGroupId": "<string>"
    },
    "error": "<string>"
  }
}

Request Body

userId · string · required

User ID, If not already created, make a user on create user page first. If already created, retrieve the user ID from get profile page.

campaignName · string · required

Descriptive name for the campaign

status · string · default: "PAUSED"

Status of the campaign

Supported values are: ACTIVE, PAUSED

budget · number · required

Campaigns daily budget amount.

startDate · string

Start Date Format: YYYY-MM-DD, use to schedule the campaign to start at a specific date.

endDate · string

End Date Format: YYYY-MM-DD, use to schedule the campaign to end at a specific date.

url · string · required

Your Website URL

specialAdCategories · string[]

Special ad categories = HOUSING, FINANCIAL_PRODUCTS_SERVICES, EMPLOYMENT

• HOUSING: Ads related to property sales, rentals, or home-related services.
  
• FINANCIAL_PRODUCTS_SERVICES: Ads promoting credit cards, loans, insurance, or other financial services.
  - EMPLOYMENT: Ads offering job opportunities or recruitment-related services.

specialAdCountries · string[]

Special Ad Countries is required if specialAdCategories is provided.

ISO 3166-1 alpha-2 country codes e.g: US,UK

utmParams · 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}}

Targeting Parameters

adSetName · string

Name of the ad set audience

gender · string

If Special Ad Category is provided, then age targeting will be ignored.

Gender targeting , 1 for male, 2 for female, and if you want to target all genders skip this parameter

ages · object

If Special Ad Category is provided, then age targeting will be ignored.

Show Age Targeting Object

minAge · number · required

Minimum target age (inclusive)

maxAge · number · required

Maximum target age (inclusive)

locations · object[] · required

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.

Show Location Targeting Object

id · string · required

Facebook location ID

type · string · required

Location types: country, region, zip, country_group, neighborhood, city

distance_unit · string

radius · number

countryCode · string

ISO 3166-1 alpha-2 country codes e.g: US,UK

countryName · string

Country Name

excludedLocations · object[]

Areas where you don’t want your ads to appear. Get excluded locations data from here

Show Location Targeting Object

id · string · required

Facebook location ID

type · string · required

Location type (city, etc.)

distance_unit · string

radius · number

countryCode · string

ISO 3166-1 alpha-2 country codes e.g: US,UK

countryName · string

Country Name

proximityTargeting · object[]

Targets people within a specific radius of a location. You have to get the proximity targeting data on your own.

Show Proximity Targeting Object

countryName · string

Country Name

distance_unit · string · required

Distance Unit, values: mile, kilometer

latitude · string · required

Latitude of the location

longitude · string · required

Longitude of the location

radius · number · required

Radius value

interests · object[]

Broad audience based on general interests (e.g., fitness, travel). Get interests data from here

Show Interests Object

id · string · required

Interest Id

name · string · required

Interest Name

type · string · required

Interest Type = interests

narrowInterests · object[]

Refines audience by requiring an additional interest match. Get narrow interests data from here

Show Narrow Interests Object

id · string · required

Interest Id

name · string · required

Interest Name

type · string · required

Interest Type = interests

furtherInterests · object[]

Adds another layer of filtering—users must match all levels. Get further narrow interests data from here

Show Further Interests Object

id · string · required

Interest Id

name · string · required

Interest Name

type · string · required

Interest Type = interests

targetLocales · number[]

Use to target specific languages. You can get the list of locales here

audienceId · string[]

Array of audience IDs, you can get the audienceId from list of audiences here

excludedAudienceIds · string[]

Audience IDs to exclude, you can get the audienceId from list of audiences here

manualPlacements · boolean · default: false

Set to false to use Advantage+ placements (recommended).

If you set to true, you have to provide facebook_positions, instagram_positions, messenger_positions

Whether placements are manually selected

facebook_positions · string[]

Facebook ad placements = feed, right_hand_column, marketplace, video_feeds, story, search, instream_video, facebook_reels, facebook_reels_overlay, profile_feed, notification

instagram_positions · string[]

Instagram ad placements = stream, story, explore, explore_home, reels, profile_feed, ig_search, profile_reels

messenger_positions · string[]

Messenger ad placements = messenger_home, story

userDevices · string[]

Device targeting, you have to send the device name in string array, you can get the list of devices from here

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.

userOS · string[]

Operating system targeting, you have to send the os platform in string array, you can get the list of operating systems from here

Dynamic Ads Parameters

campaignType · string · required

For Lead Goal, campaignType is LEAD_GENERATION

images · object[]

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

Show Image Assets Array

url · string · required

URL for image asset

videos · object[]

You can add up to 10 total images and videos in one dynamic ad, atlease 1 video is required if image is not provided.

Show Video Assets Array

video_id · string · required

Facebook video ID, get facebook video id from here

thumbnail_url · string · required

URL for video thumbnail image, get video thumbnail url from here

primaryText · object[]

You can add up to 5 primary text variations, atleast 1 primary text is required

Show Primary Text Array

text · string · required

Main ad copy text

headlines · object[]

You can include up to 5 headline variations.

Show Headline Variations Array

text · string · required

Headline text variation

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

leadsFormId · string · required

Facebook Lead Form ID, get facebook lead form id from here

callToAction · string · required

Supported call to action types are LEARN_MORE, SIGN_UP, DOWNLOAD, APPLY_NOW, SUBSCRIBE, GET_QUOTE, BOOK_TRAVEL

Response

success · boolean

Indicates that the HTTP response was successful (status code 200 OK).

results · object

Show Results Object

success · boolean

Indicates whether the specific operation or API action was successful.

campaign · object

Show Campaign Object

leadFormId · string

The unique identifier for the lead form associated with this campaign.

campaignId · string

The unique identifier for the campaign.

adId · string[]

Ad IDs Array

adGroupId · string

The unique identifier for the ad group associated with this campaign.

error · string

Error string if something went wrong