Guide to Setting Up Tags With API

Vaida
Vaida
  • Updated

A tag is a code snippet that publishers place 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.

Tip

For more information about tag settings, see Create and Customize Tags.

After you've created a direct or a programmatic line item under your campaign and order, and prepared the ad that you want to show, you need to create a tag by assigning the ad to the line item.

With Tags API, you can create, update, and retrieve tags. You can also create a list of all tags and retrieve third-party ad verification details. 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.

Authentication

To authenticate and use Adform APIs, your user account must have the necessary permissions and your OAuth client must have the required scopes assigned to it.

To create a tag, Adform DSP and Ad Server user account must have these permissions assigned by the business account admin:

  • Manage Campaigns & Orders

  • Manage Direct Line Items, Manage Programmatic Line Items, or both

  • Manage Tags

  • Pause Tags (optional)

Depending on your objectives and workflow, you'll need some or all of the following scopes assigned to your OAuth client by Adform Support (technical@adform.com):

  • https://api.adform.com/scope/tags.direct: Grants access to the DirectTags section of the Tags API.

  • https://api.adform.com/scope/tags.rtb: Grants access to RtbTags section of the Tags API.

  • https://api.adform.com/scope/tags.readonly: Grants access to the Tags section of the Tags API.

  • https://api.adform.com/scope/tags.direct.thirdpartyadverification.readonly: Grants access to the direct tag third-party ad verification endpoint in ThirdPartyAdVerifications section of the Tags API.

  • https://api.adform.com/scope/tags.rtb.thirdpartyadverification.readonly: Grants access to the RTB tag third-party ad verification endpoint in ThirdPartyAdVerifications section of the Tags API.

Tip

If you don't have an OAuth client yet, follow the procedure in Get Authentication Credentials for Adform APIs to register one.

Prerequisites

To set up a tag with API, you must use the following IDs in your requests:

ID

Used For

Retrieve From

campaignId

Specify the campaign to which the tag belongs

Campaigns Management API

baseLineItemId

Specify the direct line item ID (for direct tags) or placement ID (for RTB tags) for which to assign the ad

Direct Line Items Management API

RTB Line Items Setup API

adUuid

Specify the ad to assign to a line item

Ads API

Note

Additional IDs might be used, but the listed ones are required to pass a request.

Tag Creation Workflow

After you've created a direct or a programmatic (RTB) line item and prepared an ad, you can continue with creating a tag.

To create a tag using Tags API, you need to complete these steps:

  1. Create a direct or an RTB tag.

  2. Update the direct or the RTB tag.

  3. Retrieve the direct tag's script to send to the publisher.

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.

1. Create a Direct Tag

To create a new direct tag, use the POST endpoint in the DirectTags section of the Tags API.

See the parameter list for more information about the required and optional parameters.

Tip

To learn how to use Adform APIs, read Guide to Using Adform APIs.

2. 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 and collect tracking data.

  • 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, use the PUT endpoint in the DirectTags section of the Tags API.

Note

Replace the {id} part in the endpoint with the ID of the tag that you want to update.

See the parameter list for more information about the required and optional parameters.

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

Note

Before deploying tracking tags, clients should ensure that users have been provided with appropriate privacy information and that any required consent or other applicable privacy signals have been obtained. Tags should be configured in accordance with applicable privacy laws and data minimization principles.

To retrieve a tag's script by tag ID, use the GET endpoint in the DirectTags section of the Tags API.

Note

Replace the {id} part in the endpoint with the ID of the tag whose script you want to retrieve.

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 endpoint in the ThirdPartyAdVerifications section of the Tags API.

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.

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.

1. Create an RTB Tag

To create a new RTB tag, use the POST endpoint in the RtbTags section of the Tags API.

See the parameter list for more information about the required and optional parameters.

Tip

To learn how to use Adform APIs, read Guide to Using Adform APIs.

2. Update an RTB Tag

Tags API provides separate endpoints to:

To update all tag details, use the PUT endpoint in the RtbTags section of the Tags API.

Note

Replace the {id} part in the endpoint with the ID of the tag that you want to update.

See the parameter list for more information about the required and optional parameters.

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 endpoint in the ThirdPartyAdVerifications section of the Tags API.

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.

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, use the POST endpoint in Tags section of the Tags API.

See the parameter list for more information about the required and optional parameters.

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

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

Universal Ad IDs Update

Parameter Name

Required or Optional

Description

Direct or RTB

Enum or Example Values

Type

adIdRegistryId

Required

Ad ID Registry ID identifies the ad registry that assigned a unique ID to a video ad in the tag. Ad registration ensures that a video ad can be recognized across different platforms.

Adform supports these ad registries:

  • Clearcast (Clock Number) – 1

  • Auditel Spot ID (CUSV) – 2

  • Ad-ID.org – 3

  • ARPP (Pub-ID) – 4

RTB

1

Integer

value

Required

Value specifies the unique ID assigned to the video ad by the ad registry

RTB

AAA/BBBB123/456

String

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

Endpoints

Ads

Ads

Tags v3

Tags v3

Was this article helpful?

/
How we can make it better?

Thank you for your feedback!