Create and Manage Tags With API

Vaida
Vaida
  • Updated

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.

Tags API Use Cases

Use Tags API 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.

  • Retrieve a detailed list of all your tags and keep track of tag-wrapping status.

Prerequisites

To start working with Tags API, you must:

Required Scopes

To work with Tags API, Adform must assign the following scopes to your OAuth client:

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.

Retrieve Necessary IDs

Before you can create or update tags using Tags API, you need to retrieve the following IDs to use in your requests:

Work With Direct 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.

Create a Direct Tag

To create a new direct tag, set up your API request body in Postman:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select POST method.

  4. In the request URL field, enter https://api.adform.com/v3/buyer/tags/directtags.

  5. Copy the example request body provided under POST method in the List of API Operations section.

  6. In Postman, in the Body tab, paste the example request body.

  7. In Postman, replace the example values in request body with values relevant for your tag. See the parameter list and the request body model for more information.

  8. Click Send.

Update a Direct Tag

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:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select PUT method.

  4. 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.

  5. Copy the example request body provided within that PUT method in the List of API Operations section.

  6. In Postman, in the Body tab, paste the example request body.

  7. In Postman, replace the example values in request body with values relevant for your tag. See the parameter list and the request body model for more information.

  8. Click Send.

Retrieve a Direct Tag's Script

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:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select GET method.

  4. 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.

  5. Click Send.

Retrieve Direct Tag Verification Information

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:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select GET method.

  4. 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 with ias, the name of the Adform partner providing tag-wrapping for your tags.

  5. Click Send.

Work With RTB Tags

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.

Create an RTB Tag

To create a new RTB tag, set up your API request body in Postman:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select POST method.

  4. In the request URL field, enter https://api.adform.com/v3/buyer/tags/rtbtags.

  5. Copy the example request body provided under POST method in the List of API Operations section.

  6. In Postman, in the Body tab, paste the example request body.

  7. In Postman, replace the example values in request body with values relevant for your tag. See the parameter list and the request body model for more information.

  8. Click Send.

Update an RTB Tag

Tags API provides separate endpoints to:

To update all tag details, set up your API request body in Postman:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select PUT method.

  4. 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.

  5. Copy the example request body provided within that PUT method in the List of API Operations section.

  6. In Postman, in the Body tab, paste the example request body.

  7. In Postman, replace the example values in request body with values relevant for your tag. See the parameter list and the request body model for more information.

  8. Click Send.

Retrieve RTB Tag Verification Information

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:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select GET method.

  4. 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 with ias, the name of the Adform partner providing tag-wrapping for your tags.

  5. Click Send.

Retrieve a List of All Tags

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:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select POST method.

  4. In the request URL field, enter https://api.adform.com/v3/buyer/tags/list.

  5. Copy the example request body provided under POST method in the List of API Operations section.

  6. In Postman, in the Body tab, paste the example request body.

  7. In Postman, replace the example values in request body with values relevant for your request. See the parameter list and the request body model for more information.

  8. Click Send.

List of Tags API Parameters

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

campaignId

Required

Campaign ID specifies the campaign for which to create the tag

Both

2532

Integer

adUuid

Required

Ad UUID specifies the ad to assign to the tag

Both

a0c1fd34-4450-4341-bfba-93c81960cb17

String

name

Optional

Tag name can contain a maximum of 256 characters, including spaces

Both

Red sneakers 100x100

String

baseLineItemId

Required

Base line item ID specifies the line item ID (for direct tags) or the placement ID (for RTB tags)

Both

7745

Integer

Tag List Creation

Parameter Name

Required or Optional

Description

Direct or RTB

Enum or Example Values

Type

campaignId

Required

Filter tags by campaignId

Both

2532

Integer

baseLineItemIds

Optional

Filter tags by baseLineItemIds

Both

7745

Array

adUuid

Optional

Filter tags by adUuid

Both

a0c1fd34-4450-4341-bfba-93c81960cb17

String

active

Optional

Filter tags by active status

Both

true

Boolean

tagIds

Optional

Filter tags by tagIds

Both

123, 5321

Array

tagUuids

Optional

Filter tags by tagUuids

Both

d40543d1-65bd-4fc5-9ec6-fb4cbb32da30

Array

name

Optional

Filter tags by tag name

Both

Red sneakers 100x100

String

type

Optional

Filter tags by tag type, either RTB or direct

Both

rtb or direct

Enum

General Settings Update

Parameter Name

Required or Optional

Description

Direct or RTB

Enum or Example Values

Type

format

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

javascriptDefault, javascriptEvents, javascriptMsn, iFrame, targetUrls, or urlToXml

Enum

servingMethod

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

impressions, clicks, invisible, offline, xml, or emailMarketing

Enum

adNoticeEnabled

Required

Ad notice defines whether to display the AdChoices icon on ads served by Adform

Both

true

Boolean

name

Required

Tag name can contain a maximum of 256 characters, including spaces

Both

Red sneakers 100x100

String

clockNumber

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

AAA/BBBB123/456

String

Destination URLs Update

Parameter Name

Required or Optional

Description

Direct or RTB

Enum or Example Values

Type

tagMember

Required

Tag member parameter lists the tag members to which the destination URL applies.

If the tag has no members, set the tagMember value to null.

Both

 
"tagMember": {
      "rotatorMemberId": "c47bd8c1-ef0c-47fb-bc47-2582e8860f64",
      "scheduleMemberId": "53817a1c-7b1a-4a06-8c5d-84797e548107",
      "innerBannerId": "fb199995-5b98-4517-90d9-b2ef2900433a"
},

Object

rotatorMemberId

Optional

rotatorMemberId is specified under tagMember.

Rotator member ID specifies the tag member with a rotator ad type.

Both

c47bd8c1-ef0c-47fb-bc47-2582e8860f64

String

scheduleMemberId

Optional

scheduleMemberId is specified under tagMember.

Schedule member ID specifies the tag member with a schedule and nested rotator ad type.

Both

53817a1c-7b1a-4a06-8c5d-84797e548107

String

innerBannerId

Optional

innerBannerId is specified under tagMember.

Inner banner ID specifies the tag member with a synchronized ad type.

Both

fb199995-5b98-4517-90d9-b2ef2900433a

String

value

Required

Value specifies the destination URL that the tag’s ad leads to.

Depending on the selected type, value can be the full landing page URL together with append rules, or just the append rules that you want to add.

Both

https://www.adform.com

String

type

Required

Type defines the change that you want to make to the destination URL.

Set value to append to keep the current landing page URL and add append rules. Set value to replace to update the full destination URL.

Both

append or replace

Enum

Tracking Pixels Update

Parameter Name

Required or Optional

Description

Direct or RTB

Enum or Example Values

Type

tagMember

Required

Tag member parameter lists the tag members to which the tracking pixels apply.

If the tag has no members, set the tagMember value to null.

Both

 
"tagMember": {
      "rotatorMemberId": "c47bd8c1-ef0c-47fb-bc47-2582e8860f64",
      "scheduleMemberId": "53817a1c-7b1a-4a06-8c5d-84797e548107",
      "innerBannerId": "fb199995-5b98-4517-90d9-b2ef2900433a"
},

Object

rotatorMemberId

Optional

rotatorMemberId is specified under tagMember.

Rotator member ID specifies the tag member with a rotator ad type.

Both

c47bd8c1-ef0c-47fb-bc47-2582e8860f64

String

scheduleMemberId

Optional

scheduleMemberId is specified under tagMember.

Schedule member ID specifies the tag member with a schedule and nested rotator ad type.

Both

53817a1c-7b1a-4a06-8c5d-84797e548107

String

innerBannerId

Optional

innerBannerId is specified under tagMember.

Inner banner ID specifies the tag member with a synchronized ad type.

Both

fb199995-5b98-4517-90d9-b2ef2900433a

Stirng

impressionPixels

Optional

Impression pixels parameter lists the URLs that are used to track ad impressions.

Impression pixel URL must:

  • Start with http://, https://, or //

  • Contain a maximum of 1000 characters and no spaces

Both

https://www.adform.com

Array

clickPixels

Optional

Click pixels parameter lists the URLs that are used to track clicks on the ad.

Click pixel URL must:

  • Start with http://, https://, or //

  • Contain a maximum of 1000 characters and no spaces

Both

https://www.adform.com

Array

eventPixels

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 eventPixels value empty.

Both

 
"eventPixels": [
          {
            "value": "https://www.adform.com",
            "eventId": 25
          }
        ]

Array

value

Required

value parameter is specified under eventPixels.

Value specifies the URL that is used to track a video ad event.

Video ad event pixel URL must:

  • Start with http://, https://, or //

  • Contain a maximum of 1000 characters and no spaces

Both

https://www.adform.com

String

eventId

Required

eventId parameter is specified under eventPixels.

Event ID specifies the video completion point that fires the event tracking pixel.

Adform supports these video completion points:

  • Start point

  • 25% point

  • 50% point

  • 75% point

  • Finish point

Both

0, 25, 50, 75, or 100

Integer

External Scripts Update

Parameter Name

Required or Optional

Description

Direct or RTB

Enum or Example Values

Type

source

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:

  • Start with http://, https://, or //

  • Contain a maximum of 1000 characters and no spaces

Both

https://www.adform.com

String

scriptPosition

Required

Script position specifies the loading order of the script.

Set value to before to load the script before the ad. Set value to after to load the script after the ad loads.

Both

before or after

Enum

type

Required

Type specifies the type of the third-party script.

Set value to videoViewabilityScript for tags with video ads, and unknown for tags with other ad types.

Both

unknown or videoViewabilityScript

Enum

Line Item Update

Parameter Name

Required or Optional

Description

Direct or RTB

Enum or Example Values

Type

baseLineItemId

Required

Base line item ID specifies the line item ID

Direct

1774860

Integer

Ad Update

Parameter Name

Required or Optional

Description

Direct or RTB

Enum or Example Values

Type

adUuid

Required

Ad UUID specifies the ad to assign to the tag

Both

9a612de4-fd73-489c-ace1-181c422bba0e

String

updateName

Optional

Update name flag indicates whether to synchronize the tag name with the name of the new ad

Both

true

Boolean

Status Updates

Parameter Name

Required or Optional

Description

Direct or RTB

Enum or Example Values

Type

active

Required

Active parameter defines whether the tag is active or archived

Note

Changing 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

true

Boolean

paused

Required

Paused parameter defines whether the direct tag is active or paused

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.

Direct

false

Boolean

sentAt

Required

Sent at parameter defines the date and time when the tag was sent (in ISO 8601 format)

Direct

2023-03-20T08:27:27.748Z

String

List of API Operations

Was this article helpful?

/
How we can make it better?

Thank you for your feedback!