PopAds API Overview

Introduction

The intention of creating this API was to allow simple access to basic functionality of our system. This API is currently in early development stage and is being worked on, so new features will be added in the near future.

Base URL for every API action is:

https://www.popads.net/api/<action name>

Parameters for actions can be passed either via query arguments or URL-encoded POST data. Actions which are not modifying any data are allowed to be called via GET request, ones which are performing certain modifications are required to be called via POST request.

Number of required arguments is variable and depends on the action. However, there is one parameter required - key. It is individually assigned API access token and can be obtained in our Panel (in Account Manager section).

Response format

The service can return various content types, depending on command, using content negotiation. You must set the Accept HTTP header in your request, if the Accept HTTP header specifies the application/json content type with higher or equal priority than other content type then content is returned as JSON (with some exceptions, such as Website Code). If you do not provide valid Accept header, the request will fail, returning a 406 Not Acceptable HTTP error. Every command supports application/json, additional supported content types are provided for each command where applicable.

Action confirmation and error reporting

Response format for correctly performed actions is described in relevant sections. Error response format is generic and, if only one of formats above is accepted by client, following content is returned:

{"errors":[{"status":<HTTP code>,"code":<API error code>,"title":"<Error type>"}]}

User Status command

https://www.popads.net/api/user_status?key=<your API key>

Retrieves basic information about account (username, creation date, balance, etc).

Website Code command

Generates adcode for given website.

Website Targeting command

Allows to read/modify global and inline Website targeting lists for campaigns.

IP Targeting command

Allows to read/modify global IP targeting lists for campaigns.

Website Details command

https://www.popads.net/api/website_details/<website ID>?key=<your API key>

Retrieves Inventory details for given Website ID.

Campaign List command

https://www.popads.net/api/campaign_list?key=<your API key>

Retrieves list of campaigns.

Campaign Start command POST

https://www.popads.net/api/campaign_start?key=<your API key>&campaign_id=<campaign ID>

If campaign is paused, start it or mark as reached daily budget. If it is out of money, set it to start after top up.

Campaign Pause command POST

https://www.popads.net/api/campaign_pause?key=<your API key>&campaign_id=<campaign ID>

If campaign is running or reached daily budget, pause it. If it is out of money, set it to pause after top up.

Campaign Top Up command POST

https://www.popads.net/api/campaign_top_up?key=<your API key>&campaign_id=<campaign ID>&amount=<amount>

Top up campaign with given amount. If campaign is marked as out of budget, start it or mark as paused according to the after approval setting. Enter amount as numeric value, without currency sign, with dot (".") as decimal separator.

This command might return "Negative budgets exceeded limit" error. It means that you have campaigns, that have negative budget, and their sum exceeded our current limit. Before you'll be able to top up any campaign, you need to solve this situation, either by trying to top up via panel (you will be redirected to subsite allowing you to correct all these budgets at once), via getting campaign list and performing Empty Budget command for each of them, or by using Campaign Runout command. (see remarks below)

Campaign Empty Budget command POST

https://www.popads.net/api/campaign_empty_budget?key=<your API key>&campaign_id=<campaign ID>&amount=<amount>

Remove given amount from campaign to user balance. If resulting campaign budget is below the current minimum threshold, it is marked as out of budget. Enter amount as numeric value, without currency sign, with dot (".") as decimal separator.

If campaign has negative balance, amount parameter is ignored and may be skipped (this command will top up campaign balance to reach $0).

Campaign Runout command (POST)

https://www.popads.net/api/campaign_runout?key=<your API key>

If GET method is used, this command returns runout amount of all your campaigns, for POST request it also automatically pays the runout amount and returns a number of campaigns paid.

Report Advertiser command POST

https://www.popads.net/api/report_advertiser?key=<your API key>&<more report options>

Prepare advertiser report, optionally filtered by campaign, website ID and country. It is recommended to pass report options as POST data, as it may exceed allowed URL length.

zone=timezone-id: Valid timezone identifier, for example Europe/Berlin. This parameter is mandatory - currently it tries to detect your timezone when not specified, but it might change in the future (anyway, autodetection supports only XX:00 timezones). Half hour and 45-minute timezones, like Asia/Kolkata, are not supported for reports including data older than 48h, and it will throw an error then, so if you really need to use such timezones, ensure that you are using quick=today/yesterday mode or appropiately calculated start time.
campaigns=id1,id2...: Comma-separated list of campaigns which you want to include in the report. When not specified, all campaigns are taken into account.
websites=id1,id2...: Comma-separated list of website IDs which you want to include in the report. When not specified, no website ID filtering occurs.
countries=country1,country2...: Comma-separated list of 2-letter country codes which you want to include in the report. When not specified, no country filtering occurs.
quick=last_X_days|today|yesterday|this_month|last_month|this_year|last_year|this_week|last_week|total: Allows to generate report from predefined period without need to specify start/end time. When specified, start/end parameters are ignored.
start=unix-timestamp|YYYY-MM-DD HH:II
end=unix-timestamp|YYYY-MM-DD HH:II: Start/end of report. Can be provided as UNIX timestamp or ISO date format. When ignored, and quick parameter is not specified, quick=total is assumed.
fdow=monday|sunday: First day of week for datetime calculations. When not specified, monday is assumed.
groups=country,campaign,website,datetime:hour|day|week|month|year: Comma-separated list of fields to group by. Date/time grouping requires a period specifier (one of above). If ommitted, one summary row is returned.
orders=cost:asc|desc,impressions:asc|desc,datetime:asc|desc,...: Comma-separated list of fields to order by. You can sort by cost, impressions, or any of fields from groups. Each field is specified by its name and :asc or :desc suffix. To sort by campaign ID, use campaign_id:asc|desc (available when grouped by campaigns). Remember to properly encode this argument.

Report Publisher command POST

https://www.popads.net/api/report_publisher?key=<your API key>&<more report options>

Prepare publisher report, optionally filtered by website and country. It is recommended to pass report options as POST data, as it may exceed allowed URL length.

websites=id1,id2...: Comma-separated list of websites which you want to include in the report. When not specified, all websites are taken into account.
countries=country1,country2...: Comma-separated list of 2-letter country codes which you want to include in the report. When not specified, no country filtering occurs.
groups=country,website,datetime:hour|day|week|month|year: Comma-separated list of fields to group by. Date/time grouping requires a period specifier (one of above). If ommitted, one summary row is returned.
orders=revenue:asc|desc,impressions:asc|desc,datetime:asc|desc,...: Comma-separated list of fields to order by. You can sort by revenue, impressions, or any of fields from groups. Each field is specified by its name and :asc or :desc suffix. To sort by website ID, use website_id:asc|desc (available when grouped by websites). Remember to properly encode this argument.
zone=timezone-id
quick=last_X_days|today|yesterday|this_month|last_month|this_year|last_year|this_week|last_week|total
start=unix-timestamp|YYYY-MM-DD HH:II
end=unix-timestamp|YYYY-MM-DD HH:II
fdow=monday|sunday: See Report Advertiser command for description.

PopAds API

Working draft