Skip to main content
Dynamic Ad
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>",
  "optimizationGoal": "<string>",
  "images": [
    {
      "url": "<string>"
    }
  ],
  "videos": [
    {
      "video_id": "<string>",
      "thumbnail_url": "<string>"
    }
  ],
  "primaryText": [
    {
      "text": "<string>"
    }
  ],
  "headlines": [
    {
      "text": "<string>"
    }
  ],
  "callToAction": "<string>"
}
'
{
  "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 campaignSupported 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.
​
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.
If Audience ID is provided, then location targeting is optional
List of areas where you want to show your ads. Get locations data from here
​
excludedLocations
object[]
Areas where you don’t want your ads to appear. Get excluded locations data from here
​
proximityTargeting
object[]
Targets people within a specific radius of a location. You have to get the proximity targeting data on your own.
​
interests
object[]
Broad audience based on general interests (e.g., fitness, travel). Get interests data from here
​
narrowInterests
object[]
Refines audience by requiring an additional interest match. Get narrow interests data from here
​
furtherInterests
object[]
Adds another layer of filtering—users must match all levels. Get further narrow interests data from here
​
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 Awareness Goal, campaignType is OUTCOME_AWARENESS
​
optimizationGoal
string
required
Supported values REACH, THRUPLAY
  • Use Optimization Goal REACH, When you want to increase reach of your campaign and show your ads to as many people as possible.
  • Use Optimization Goal THRUPLAY, When you want to show your ads to people who will watch the entire video.
​
images
object[]
Images are only supported for optimization goal REACH.
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
​
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.
​
primaryText
object[]
You can add up to 5 primary text variations, atleast 1 primary text is required
​
headlines
object[]
You can include up to 5 headline variations.
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
​
callToAction
string
required
Supported call to action types are LEARN_MORE, SHOP_NOW, SIGN_UP, DOWNLOAD, WATCH_MORE, APPLY_NOW, SUBSCRIBE, GET_QUOTE, CONTACT_US, ORDER_NOW, REQUEST_TIME, GET_SHOWTIMES, LISTEN_NOW, SEE_MENU, BOOK_TRAVEL

​
Response

​
success
boolean
Indicates that the HTTP response was successful (status code 200 OK).
​
results
object