Buyer side Guide
Structure of Adform's platform
Adform's platform is structured as shown below:
If you want to create a new user, get an API access or download our Postman based API collection, please, read our User Set-up Guide
Currently there are two methods to authenticate into Adform’s platform.
Adform’s in-house ticket based authentication
In order to authenticate you have to use your user's username and password and provide it to the https://api.adform.com/Services/Security/Login POST endpoint in the body of an API query likein the following example:
API will return you your ticket, that you have to provide in every subsequent API query in order to get permission to use APIs. Response will look like this:
Keep in mind that ticket is valid for 1 hour, so after 1 hour you have to get a new ticket
An application (OAuth client) needs to be registered so that it can get access token and consume API services.
For a full authentication flow please refer to our Authorization Guide.
- All new Adform’s APIs will support OAuth2 from 01 February 2017
- Legacy in-house ticket based authentication will be deprecated by 01 September 2017
For more information, please, contact API support at email@example.com
To create a campaign you have to use https://api.adform.com/Services/Campaign/Campaigns POST endpoint, while also providing your authentication ticket in the header. Request body has to be in JSON format.
Full extensive list of mandatory and optional parameters for campaign creation API request can be found here.
Here is an example of a campaign creation:
Other campaign management APIs
Management – read more here
Alerts – read more here
Attribute settings – read more here
Labels – read more here
Landing pages – read more here
RTB settings – read more here
What are they?
Orders in Adform’s platform could be called “folders” for line items. They do not play an essential role. However, they are used for convenience. You can place multiple line items in one order and if you deactivate an order all line items that are located under it will be paused.
Default order is created when you create your first campaign
More about orders
Direct media order management – read more here
RTB order management – read more here
Line items are the main tool for launching an ad. Each order can consist up to 100 line items. This is where you set your runtime dates, budgets, targeting, etc.
Line items are divided into two types:
Creating line item
To create an RTB line item, you have to use https://api.adform.com/Services/RTBActivity/v20141111/Activities POST endpoint, while also providing your authentication ticket in the header.
Here is an example of an RTB line item creation:
A successful response should look like this:
Updating line item
Line items can be updated any time using API. To update line item use https://api.adform.com/Services/RTBActivity/v20141111/Activities PUT endpoint. Also, do not forget to include your authentication ticket in a header of API request.
P.S. Each time you update line item, you must provide every parameter in API request body or else they will be reset to default values.
You can use GET Line Item method to retrieve a full set of parameters of a line item
Here is an example workflow of updating line item to pause it:
1. Get existing line item list of parameters
2. Make changes and insert it into a body of Update Line Item (PUT method).
3. Receive response
Banners are your ads, they are what customers see. Various types of banners can be created and managed using Adform’s API such as:
- HTML banners
- Image banners
- Video banners
- Flash banners
Learn more about banner creation here.
Banners can also be put into rotators. Rotator is a set few banners that are shown interchangeably depending on your needs. Rotators can also be optimized for CTR, etc.
Learn more about rotators management here.
Here is an example of Image Banner creation using API. In the request body you have to provide:
- File name
- Image file encoded in base64
- Campaign ID
- Desired banner title
Response contains “Value”, which is banner's UUID that is used to associate Line Item with a banner through Tags.
For direct campaigns tags are acting as serving scripts that are implemented by websites and are usually serving one banner, rotator or schedule. Each tag has a unique identifier that is also visible in banner object after the banner is served.
For RTB campaigns tags are acting as a match point between a designated banner and inventory. The generated serving script doesn't have to be implemented to the publisher's website as the banner is loaded through a master tag.
Learn more about Tag management here.
In order to use these APIs one's account has to have additional rights enabled.
To have Reporting Stats API access enabled, please, contact firstname.lastname@example.org
Reporting APIs allows to get data that can be used to track performance of your campaing.
Learn more about overall Reporting API here.
Reporting Stats API
Reporting Stats API allows you to build custom reports by choosing certain dimensions and metrics. To get started, you have to decide what kind of data you want to receive.
Then, choose desired metrics, dimensions and, if need be, filters, paging and sorting. To get an extensive list of available parameters, metadata API can be used – read more here for Metrics and here for Dimensions.
To get clicks and impressions of each campaign, API request would look like this:
The response looks like this:
Master Data API
It is also possible to receive raw data that one can use in their own statistical tool to reach conclusions. This is done using Master Data API.
In order to use Master Data API, additional rights has to be enabled. Please, contact email@example.com to have them enabled.
Info to keep in mind:
- Information is updated every hour
- Each file contains only new data
- Master Data is additionally paid service
Master Data API request should look like this:
In the API endpoint you have to provide your Master Data ID and header must contain the authentication ticket that you received from this API.
Master Data API response:
In the response body, there are links for downloading files together with sizes and creation dates.
If you want to learn more about Master data API please click here.
This service allows you to manage tracking points. Creating a tracking code and implementing it into your website automatically creates a tracking point. You can get a list of tracking points at advertiser level using GET Tracking Points method.