A tag is a code snippet that a publisher places into an ad slot to show an ad on their page. Tags can have different formats, such as HTML or IMG for display ads, and VAST and VPAID for video ads. The purpose of a tag is to fetch specific information and carry out other processes within the webpage or mobile app to successfully deliver an ad. Additionally, a tag can include a tracking script that you send to publishers to track clicks or impressions on your ads.
With Tags API, you can create, update, and retrieve tags. Tags API categorizes tags based on line item type, separating the workflows for direct and programmatic (also called RTB) tags. Therefore, you can work only with the tag type that is relevant to you — with direct tags for Adform Ad Server, RTB tags for Adform DSP, or both.
We recommend using Tags API if you:
-
Seek to optimize the tag creation and updating process to manage all your tags from your own system or from the third-party tools that you use.
-
Need to retrieve a detailed list of all your tags and keep track of tag-wrapping status.
To start working with Tags API, you must:
-
Have an Adform DSP or Ad Server account.
-
Have an API-specific user account within your business account.
-
Have the necessary permissions assigned to the API user account:
-
Manage Campaigns & Orders
-
Manage Direct Line Items
-
Manage Programmatic Line Items
-
Manage Tags
-
Pause Tags (optional)
-
-
Get your OAuth credentials and all necessary access.
-
Retrieve the necessary IDs for Tags API calls.
To work with Tags API, Adform must assign the following scopes to your OAuth client:
-
https://api.adform.com/scope/tags.direct: Yields full access to the direct tags endpoints of the API.
-
https://api.adform.com/scope/tags.direct.readonly: Yields read-only access to the direct tags endpoints of the API.
-
https://api.adform.com/scope/tags.rtb: Yields full access to the RTB tags endpoints of the API.
-
https://api.adform.com/scope/tags.rtb.readonly: Yields read-only access to the RTB tags endpoints of the API.
-
https://api.adform.com/scope/tags.readonly: Yields read-only access to list endpoint of the API.
-
https://api.adform.com/scope/tags.direct.thirdpartyadverification.readonly: Yields read-only access to the direct tags third-party ad verification endpoint of the API.
-
https://api.adform.com/scope/tags.rtb.thirdpartyadverification.readonly: Yields read-only access to the RTB tags third-party ad verification endpoint of the API.
To get the required access, contact Adform Support (technical@adform.com) with your OAuth client and the list of needed scopes.
Tip
If you don't have an OAuth client yet, follow the procedure in Get Authentication Credentials to Authorize With Adform APIs to register one.
Before you can create or update tags using Tags API, you need to retrieve the following IDs to use in your requests:
-
Line item ID (for direct tags) or Placement ID (for RTB tags)
The DirectTags section of Tags API provides the endpoints to work specifically with direct tags — create new tags, update all or selected tag settings, retrieve tag information or tag script by tag ID.
To create a new direct tag, set up your API request body in Postman:
-
Open the Postman desktop app.
-
Click to open a new tab.
-
In the dropdown menu, select POST method.
-
In the request URL field, enter https://api.adform.com/v3/buyer/tags/directtags.
-
Copy the example request body provided under POST method in the Swagger documentation.
-
In Postman, in the Body tab, paste the example request body.
-
In Postman, replace the example values in request body with values relevant for your tag. See the parameter list and the Swagger model for more information.
-
Click Send.
Tags API provides separate endpoints to:
-
Update all tag details
-
Add or update external scripts
-
Update destination URLs
-
Update general settings
-
Add or update tracking pixels
-
Replace the tag's ad
-
Replace the line item that the tag belongs to
-
Pause direct tags by updating the paused status (works only if the user account has the Pause Tag permission)
Note
Pausing a direct tag won’t stop its delivery. If you pause a direct tag, your display ad will be empty. Clicks on the empty ad will still lead to the landing page, but won't collect tracking data. You will not be charged for ad delivery from paused tags.
-
Change the tag's active status to archive or restore the tag
Note
Changing a direct tag’s active status won’t stop its delivery. To stop ad delivery for archived direct tags, contact the publisher and request the removal of your tags.
-
Update the tag's sent status
To update all tag details, set up your API request body in Postman:
-
Open the Postman desktop app.
-
Click to open a new tab.
-
In the dropdown menu, select PUT method.
-
In the request URL field, enter https://api.adform.com/v3/buyer/tags/directtags/{id}.
Note
Replace the
{id}
part in the endpoint with the ID of the tag that you want to update. -
Copy the example request body provided within that PUT method in the Swagger documentation.
-
In Postman, in the Body tab, paste the example request body.
-
In Postman, replace the example values in request body with values relevant for your tag. See the parameter list and the Swagger model for more information.
-
Click Send.
Adform generates and loads specific serving scripts for each unique environment where the direct tag is served. A serving script initiates the connection with the ad server, loads the ad, correctly positions it within the page, and collects the engagement metrics like viewability, mouse overs, and heat map parameters.
To retrieve a tag's script by tag ID, use the GET method in Postman:
-
Open the Postman desktop app.
-
Click to open a new tab.
-
In the dropdown menu, select GET method.
-
In the request URL field, enter https://api.adform.com/v3/buyer/tags/directtags/{id}/script.
Note
Replace the
{id}
part in the endpoint with the ID of the tag whose script you want to retrieve. -
Click Send.
In the ThirdPartyAdVerifications section of Tags API, you can retrieve the tag-wrapping status of your direct tags.
Note
This feature is currently available only for Integral Ad Science (IAS) clients that have linked their Adform and IAS campaigns.
To retrieve tag-wrapping information by tag ID, use the GET method in Postman:
-
Open the Postman desktop app.
-
Click to open a new tab.
-
In the dropdown menu, select GET method.
-
In the request URL field, enter https://api.adform.com/v3/buyer/tags/directtags/{id}/thirdpartyadverification/{partner}.
Note
Replace the
{id}
part in the endpoint with the ID of the tag that you want to retrieve measurement information for.Replace
{partner}
part in the endpoint withias
, the name of the Adform partner providing tag-wrapping for your tags. -
Click Send.
The RtbTags section of Tags API provides the endpoints to work specifically with RTB tags — create new tags, update all or selected tag settings, retrieve tag information by tag ID.
To create a new RTB tag, set up your API request body in Postman:
-
Open the Postman desktop app.
-
Click to open a new tab.
-
In the dropdown menu, select POST method.
-
In the request URL field, enter https://api.adform.com/v3/buyer/tags/rtbtags.
-
Copy the example request body provided under POST method in the Swagger documentation.
-
In Postman, in the Body tab, paste the example request body.
-
In Postman, replace the example values in request body with values relevant for your tag. See the parameter list and the Swagger model for more information.
-
Click Send.
Tags API provides separate endpoints to:
-
Update all tag details
-
Add or update tracking pixels
-
Update destination URLs
-
Update general settings
-
Add or update external scripts
-
Replace the tag's ad
-
Change the tag's active status to archive or restore the tag
Note
Changing an RTB tag’s active status to
false
will archive the tag and stop its delivery.
To update all tag details, set up your API request body in Postman:
-
Open the Postman desktop app.
-
Click to open a new tab.
-
In the dropdown menu, select PUT method.
-
In the request URL field, enter https://api.adform.com/v3/buyer/tags/rtbtags/{id}.
Note
Replace the
{id}
part in the endpoint with the ID of the tag that you want to update. -
Copy the example request body provided within that PUT method in the Swagger documentation.
-
In Postman, in the Body tab, paste the example request body.
-
In Postman, replace the example values in request body with values relevant for your tag. See the parameter list and the Swagger model for more information.
-
Click Send.
In the ThirdPartyAdVerifications section of Tags API, you can retrieve the tag-wrapping status of your RTB tags.
Note
This feature is currently available only for Integral Ad Science (IAS) clients that have linked their Adform and IAS campaigns.
To retrieve tag-wrapping information by tag ID, use the GET method in Postman:
-
Open the Postman desktop app.
-
Click to open a new tab.
-
In the dropdown menu, select GET method.
-
In the request URL field, enter https://api.adform.com/v3/buyer/tags/rtbtags/{id}/thirdpartyadverification/{partner}.
Note
Replace the
{id}
part in the endpoint with the ID of the tag that you want to retrieve measurement information for.Replace
{partner}
part in the endpoint withias
, the name of the Adform partner providing tag-wrapping for your tags. -
Click Send.
You can retrieve a comprehensive list of all existing tags within your campaign (direct and RTB tags included) and filter the results by line item IDs, ad UUIDs, tag IDs, tag UUIDs, tag name, tag type, or active status.
To retrieve a list of all existing tags, set up your API request body in Postman:
-
Open the Postman desktop app.
-
Click to open a new tab.
-
In the dropdown menu, select POST method.
-
In the request URL field, enter https://api.adform.com/v3/buyer/tags/list.
-
Copy the example request body provided under POST method in the Swagger documentation.
-
In Postman, in the Body tab, paste the example request body.
-
In Postman, replace the example values in request body with values relevant for your request. See the parameter list and the Swagger model for more information.
-
Click Send.
These are the parameters that you must define when creating or updating tags:
Tag Creation
Parameter Name |
Required or Optional |
Description |
Direct or RTB |
Enum or Example Values |
Type |
---|---|---|---|---|---|
|
Required |
Campaign ID specifies the campaign for which to create the tag |
Both |
|
Integer |
|
Required |
Ad UUID specifies the ad to assign to the tag |
Both |
|
String |
|
Optional |
Tag name can contain a maximum of 256 characters, including spaces |
Both |
|
String |
|
Required |
Base line item ID specifies the line item ID (for direct tags) or the placement ID (for RTB tags) |
Both |
|
Integer |
Tag List Creation
Parameter Name |
Required or Optional |
Description |
Direct or RTB |
Enum or Example Values |
Type |
---|---|---|---|---|---|
|
Required |
Filter tags by |
Both |
|
Integer |
|
Optional |
Filter tags by |
Both |
|
Array |
|
Optional |
Filter tags by |
Both |
|
String |
|
Optional |
Filter tags by |
Both |
|
Boolean |
|
Optional |
Filter tags by |
Both |
|
Array |
|
Optional |
Filter tags by |
Both |
|
Array |
|
Optional |
Filter tags by tag |
Both |
|
String |
|
Optional |
Filter tags by tag |
Both |
|
Enum |
General Settings Update
Parameter Name |
Required or Optional |
Description |
Direct or RTB |
Enum or Example Values |
Type |
---|---|---|---|---|---|
|
Required |
Format specifies the tag format to use when delivering ads. Tag format depends on the type of ad assigned to the tag and the requirements of the selected publisher. |
Direct |
|
Enum |
|
Required |
Serving method specifies the ad serving method to use when delivering ads. Ad serving method depends on the type of ad assigned to the tag and on who hosts the ad (Adform or the selected publisher). |
Direct |
|
Enum |
|
Required |
Ad notice defines whether to display the AdChoices icon on ads served by Adform |
Both |
|
Boolean |
|
Required |
Tag name can contain a maximum of 256 characters, including spaces |
Both |
|
String |
|
Optional |
Clock number identifies the video ad assigned to the tag and the ad's source. Adform uses clock number to ensure that a video ad complies with the requirements set in the UK Codes of Advertising. |
RTB |
|
String |
Destination URLs Update
Parameter Name |
Required or Optional |
Description |
Direct or RTB |
Enum or Example Values |
Type |
---|---|---|---|---|---|
|
Required |
Tag member parameter lists the tag members to which the destination URL applies. If the tag has no members, set the |
Both |
"tagMember": { "rotatorMemberId": "c47bd8c1-ef0c-47fb-bc47-2582e8860f64", "scheduleMemberId": "53817a1c-7b1a-4a06-8c5d-84797e548107", "innerBannerId": "fb199995-5b98-4517-90d9-b2ef2900433a" }, |
Object |
|
Optional |
Rotator member ID specifies the tag member with a rotator ad type. |
Both |
|
String |
|
Optional |
Schedule member ID specifies the tag member with a schedule and nested rotator ad type. |
Both |
|
String |
|
Optional |
Inner banner ID specifies the tag member with a synchronized ad type. |
Both |
|
String |
|
Required |
Value specifies the destination URL that the tag’s ad leads to. Depending on the selected |
Both |
|
String |
|
Required |
Type defines the change that you want to make to the destination URL. Set value to |
Both |
|
Enum |
Tracking Pixels Update
Parameter Name |
Required or Optional |
Description |
Direct or RTB |
Enum or Example Values |
Type |
---|---|---|---|---|---|
|
Required |
Tag member parameter lists the tag members to which the tracking pixels apply. If the tag has no members, set the |
Both |
"tagMember": { "rotatorMemberId": "c47bd8c1-ef0c-47fb-bc47-2582e8860f64", "scheduleMemberId": "53817a1c-7b1a-4a06-8c5d-84797e548107", "innerBannerId": "fb199995-5b98-4517-90d9-b2ef2900433a" }, |
Object |
|
Optional |
Rotator member ID specifies the tag member with a rotator ad type. |
Both |
|
String |
|
Optional |
Schedule member ID specifies the tag member with a schedule and nested rotator ad type. |
Both |
|
String |
|
Optional |
Inner banner ID specifies the tag member with a synchronized ad type. |
Both |
|
Stirng |
|
Optional |
Impression pixels parameter lists the URLs that are used to track ad impressions. Impression pixel URL must:
|
Both |
|
Array |
|
Optional |
Click pixels parameter lists the URLs that are used to track clicks on the ad. Click pixel URL must:
|
Both |
|
Array |
|
Optional |
Event pixels parameter lists the URLs that are used to track video ad events. If the tag has no video ad event pixels, leave the |
Both |
"eventPixels": [ { "value": "https://www.adform.com", "eventId": 25 } ] |
Array |
|
Required |
Value specifies the URL that is used to track a video ad event. Video ad event pixel URL must:
|
Both |
|
String |
|
Required |
Event ID specifies the video completion point that fires the event tracking pixel. Adform supports these video completion points:
|
Both |
|
Integer |
External Scripts Update
Parameter Name |
Required or Optional |
Description |
Direct or RTB |
Enum or Example Values |
Type |
---|---|---|---|---|---|
|
Required |
Source specifies the third-party script URL that is used to extend your ad functionality with features of other systems. Third-party script URL must:
|
Both |
|
String |
|
Required |
Script position specifies the loading order of the script. Set value to |
Both |
|
Enum |
|
Required |
Type specifies the type of the third-party script. Set value to |
Both |
|
Enum |
Line Item Update
Parameter Name |
Required or Optional |
Description |
Direct or RTB |
Enum or Example Values |
Type |
---|---|---|---|---|---|
|
Required |
Base line item ID specifies the line item ID |
Direct |
|
Integer |
Ad Update
Parameter Name |
Required or Optional |
Description |
Direct or RTB |
Enum or Example Values |
Type |
---|---|---|---|---|---|
|
Required |
Ad UUID specifies the ad to assign to the tag |
Both |
|
String |
|
Optional |
Update name flag indicates whether to synchronize the tag name with the name of the new ad |
Both |
|
Boolean |
Status Updates
Parameter Name |
Required or Optional |
Description |
Direct or RTB |
Enum or Example Values |
Type |
---|---|---|---|---|---|
|
Required |
Active parameter defines whether the tag is active or archived NoteChanging a direct tag's active status won't impact its delivery. Changing an RTB tag's active status will stop or resume its delivery. |
Both |
|
Boolean |
|
Required |
Paused parameter defines whether the direct tag is active or paused NotePausing a direct tag won’t stop its delivery. If you pause a direct tag, your display ad will be empty. Clicks on the empty ad will still lead to the landing page, but won't collect tracking data. |
Direct |
|
Boolean |
|
Required |
Sent at parameter defines the date and time when the tag was sent (in ISO 8601 format) |
Direct |
|
String |