How to create an Advertising Campaign by using API?
Method: POST /api/v1/advertiser/campaign
Description: You can create an advertising campaign via API for your HilltopAds advertising account.
Please note that this method is available only for the formats Popunder mobile and Popunder desktop.
Parameters:
name | description | example | comment |
key | A unique API key that you can generate in the API section of your HilltopAds account | nXzgO3Bc | This is a required parameter in the request. |
format | Advertising format for which the campaign needs to be created. | Popunder mobile | You can specify only one advertising format. This is a required parameter in the request. |
rate | Price for 1000 impressions (CPM). | 1.53 | All prices (rate) are specified in the request without currency, but will be set in USD in the result. This is a required parameter in the request. |
capTotal | Impression frequency cap. This parameter indicates the number of times an ad is shown. | 2 | You can specify only one number. |
capResetAfter | Impression frequency cap. This parameter indicates how long to show the ad. | 12 | You can specify only one number. |
capForCampaign | Impression frequency cap. This parameter indicates whether the rule applies to the campaign or the banner. | campaign | For the Popunder format, you can only specify campaign. |
channels | Segment and traffic category for which the ad needs to be launched. | Mainstream/non-mainstream High activity Mainstream/non-mainstream Medium activity Mainstream/non-mainstream Low activity | To specify multiple activity segments, list them with commas. Note, you can only specify one traffic category - mainstream or non-mainstream. This is a required parameter in the request. |
type | Type of an ad campaign | CPM, CPC | Please note, currently you can only specify CPM campaign type. This is a required parameter in the request. |
name | Name of an advertising campaign. | Popunder_API | The campaign name must be unique and not repeated with names of already created campaigns. This is a required parameter in the request. |
url | Offer URL link where the traffic needs to be sent. |
| You can specify only one link. This is a required parameter in the request. |
active | Specify the status of the created campaign: true - ON, false - OFF. | True, false | When specifying the campaign status as True (ON), the campaign will become active only after moderation. |
limitImpressionsTotal | Specify the Total Impressions Limit | 200000 | You can specify only one number. |
limitImpressionsDaily | Specify the Daily Impressions Limit | 20000 | You can specify only one number. The min. daily impressions limit is 15,000. |
limitBudgetTotal | Specify the Total Budget Limit | 2000 | You can specify only one number. |
limitBudgetDaily | Specify the Daily Budget Limit | 50 | You can specify only one number. The min. daily budget limit is $20. |
filters | You can allow/disallow Proxy and WebView traffic filters. | Proxy WebView | These parameter is passed as an object. |
targeting | Required targeting settings for the advertising campaign.
| geo browser os device mobilecarrier iprange osversions App | These parameters are passed as an object. Each new targeting parameter is specified with a comma. |
uniformDistributionDaily | Choose how the campaign limits should be reached. | ASAP Evenly | Asap – reach the specified campaign limits as quickly as possible |
Targeting object
Name | Example | Description |
geo | US GB AU | Enter the two-letter code of the required country/countries, separated by commas. |
browser | Chrome FireFox Safari |
|
os | Android iOS |
|
device | mobile/smartphone tablet |
|
mobilecarrier | AU~vodafone |
|
iprange | 127.0.0.1 |
|
osversions | iOS 15 Win 7 |
All available versions Win 11, Win 10, Win 8, Win 7, Vista, XP, Win phone 6, Win phone 7, Win phone 8, Win phone 10, Android 1, Android 2, Android 3, Android 4, Android 5, Android 6, Android 7, Android 8, Android 9, Android 10, Android 11, Android 12, Android 13, Android 14, Android 15, Android 16, iOS 4, iOS 5, iOS 6, iOS 7, iOS 8, iOS 9, iOS 10, iOS 11, iOS 12, iOS 13, iOS 14, iOS 15, iOS 16, iOS 17, iOS 18, iOS 26, Leopard 10.5, Snow Leopard 10.6, Lion 10.7, Mountain Lion 10.8, Mavericks 10.9, Yosemite 10.10, El Capitan 10.11, Sierra 10.12, High Sierra 10.13, Mojave 10.14, Catalina 10.15, BigSur 11.0, Monterey 12.0, Ventura 13.0, Sonoma 14.0, Sequoia 15.5 |
App |
|
Targeting object
Name | Example |
Proxy | Allow Disallow Only |
WebView | Allow Disallow Only |
Request Example:
To create an advertising campaign with the following parameters:
Ad format - Popunder mobile
Rate - $1.53
Frequency cappings - 2 display per 12 hours for campaign
Channels - mainstream high activity и medium activity
Type - CPM (for a Popunder ad format you can specify only CPM)
Name - Popunder_API
URL -
https://mywebsite.com.Active - True
Targeting - GEO: US, UK, DE; Browser: Chrome, Safari; Device - mobile
Please note that if your link contains the '&' symbol, you need to encode it to URL-encoded format. Otherwise, you may receive an error in the response to the link change request.
For example, the link
https://mywebsite.com/?token={{ctoken}}&zone={{zone_id}}should be specified as
https%3A%2F%2Fmywebsite.com%2F%3Ftoken%3D%26zone%3D
To encode your link to URL-encoded format, you can use the tool.
You need to write a request in the following format:
curl -X POST --data '{"format":"Popunder mobile","channels":["Mainstream High Activity", "Mainstream Medium Activity"],"type":"CPM","rate":1.53,"name":"Popunder_API","url":"https%3A%2F%2Fmywebsite.com%2F%3Ftoken%3D%26zone%3D","active":true,"capTotal":2,"capResetAfter":12,"capForCampaign":"campaign","limitImpressionsDaily":20000,"limitBudgetTotal":"2000","limitBudgetDaily":"50","filters":{"Proxy":"Only"},"targeting":{"geo":{"operator":"in","operand":["US","UK","DE"]},"browser":{"operator":"in","operand":["Chrome","Safari"]},"device":{"operator":"in","operand":["Mobile/smartphone"]}}}' https://api.hilltopads.com/v1/advertiser/campaign?key=nXzgO3BcUnlock the full potential of the HilltopAds ad network API!