Ad Manager REST API

Everything in Aeon Ad Manager can also be done through its REST API: ads, creatives, HTML5 packages, groups, placements, bookings, preview links and statistics. An agency or a coding agent can deliver a finished campaign without logging in to WordPress, and the newspaper sees and controls all of it in Ad Manager.

The step-by-step instructions for a coding agent are in the agent brief, which is also in the starter kit. How the formats are built is described in Building high impact formats.

Roles

A person who only works with ads gets a WordPress account that reaches Ad Manager and nothing else. The newspaper chooses the role when it adds the user.

Role	Can
Ad manager	Everything in Ad Manager, including the site’s ad rules, ads.txt, the statistics settings, the import and ads with their own code (HTML, AdSense, Google Ad Manager)
Ad agency	Ads, HTML5 packages, groups, placements, bookings, preview links and statistics. Not the settings, the import or ads with their own code
Ad reports	Reads the statistics

Code ads are kept to the newspaper’s own staff, because their code runs on the site itself. HTML5 packages run in a locked frame, so the agency role can upload them.

Logging in

• Address: https://<site>/wp-json/aeon-ad-manager/v1/.
• Login: the user name and an application password, created under the user’s profile in WordPress, with HTTP Basic over HTTPS.
• Keep the password in a secret store, never in code, logs or prompts.
• An application password can be revoked at any time without affecting the user’s normal password.

curl --user "$WP_USER:$WP_APP_PASSWORD" "$SITE/wp-json/aeon-ad-manager/v1/placements/map"

A delivery, step by step

Step	Call
Upload poster images	POST /wp-json/wp/v2/media
Check the HTML5 package	POST packages?dry_run=1, which answers ok or the error, and stores nothing
Upload the package	POST packages
Create the ad as a draft	POST ads with "status":"draft"
Add the creative	POST creatives with the format, its settings and the landing pages
Make it the ad’s creative	PATCH ads/<id> with active_creative_id
Preview	POST creatives/<id>/preview-link, which gives a link that works for seven days
Book it, after approval	POST campaigns, POST flights, then the flight’s ads and placements
…or add it to a group	PUT groups/<id>/members with the whole list of members and weights
Activate	PATCH ads/<id> with "status":"active"
Follow up	GET placements/map, GET ads/<id>/report and the ad’s public statistics page

How the API behaves:

• Times are UTC, and an end time is exclusive.
• Changing an ad needs its current revision. A stale one is refused with 409, so two people cannot overwrite each other.
• A creative never changes. A new version is a new creative, and each version keeps its own statistics.

Previews instead of test ads

Nothing is ever tested live. The preview link shows the creative on a real page of the site:

• topscroll and skin on the front page, other formats in the newest article;
• every other ad on that page left out;
• nothing counted, and a click only shows where it would have gone.

The newspaper’s staff can also make preview links on the ad’s page in Ad Manager.

Errors

Status	Meaning
400	Something in the request is wrong; the message says what
401	The login failed
403	The role may not do this, or the preview link is not valid
404	The ID does not exist
409	A stale revision, or an attempt to change a creative
410	The preview link has expired

The complete reference, with every field and rule, ships with the plugin. The agent brief covers everything an agency needs.