Tags V3 — Migration Guide

Vaida
Vaida
  • Updated

API Name (Version)

Deprecation Date

Sunset Date

Unified Tags (V1)

May 31, 2024

December 31, 2024

With Tags V3, you can create, update, and retrieve RTB (programmatic) and direct tags. Tags V3 categorizes tags based on their line item type, separating the workflows for direct and RTB tags. Therefore, you can work only with the tag type that is relevant to you — with direct tags for Ad Server, RTB tags for DSP, or both. In addition, while Unified tags (V1) endpoints accepted both tag IDs and UUIDs, Tags V3 only works with tag IDs.

If you have been using any Unified Tags (V1) endpoint, follow this guide to migrate Unified Tags to Tags V3 before the sunset date (December 31, 2024). For all the information about Tags V3 endpoints, see Tags V3 Setup.

Understand Affected API Endpoints

Endpoints to Deprecate

New Endpoints

Use Case

GET /v1/buyer/unifiedtags/single/{id}

GET /v3/buyer/tags/directtags/{id}

GET /v3/buyer/tags/rtbtags/{id}

Retrieve a direct tag by tag ID.

Retrieve an RTB tag by tag ID.

GET /v1/buyer/unifiedtags/single/{uuid}

The new endpoints only accept tag IDs. To retrieve a tag, use the endpoints:

GET /v3/buyer/tags/directtags/{id}

GET /v3/buyer/tags/rtbtags/{id}

Retrieve a direct tag by tag ID.

Retrieve an RTB tag by tag ID.

DELETE /v1/buyer/unifiedtags/{uuid}

The new endpoints only accept tag IDs. With Tags V3 you can't delete tags, only deactivate them. To deactivate a tag, use the endpoints:

PUT /v3/buyer/tags/directtags/{id}/active

PUT /v3/buyer/tags/rtbtags/{id}/active

Update a direct tag’s active status by tag ID.

Update an RTB tag’s active status by tag ID.

POST /v1/buyer/unifiedtags/list

POST /v3/buyer/tags/list

Retrieve a list of existing tags.

GET /v1/buyer/unifiedtags/{campaignId}

To retrieve tags by campaign ID, use the endpoint with campaignId in the filter:

POST /v3/buyer/tags/list

Retrieve a list of existing tags from a specific campaign.

POST /v1/buyer/unifiedtags

POST /v3/buyer/tags/directtags

POST /v3/buyer/tags/rtbtags

Create a new direct tag.

Create a new RTB tag.

PUT /v1/buyer/unifiedtags

PUT /v3/buyer/tags/directtags/{id}

PUT /v3/buyer/tags/rtbtags/{id}

Update a direct tag by tag ID.

Update an RTB tag by tag ID.

POST /v1/buyer/unifiedtags/async

Tags V3 doesn't provide the functionality to create tags in bulk. To create a tag, use the endpoints:

POST /v3/buyer/tags/directtags

POST /v3/buyer/tags/rtbtags

Create a new direct tag.

Create a new RTB tag.

PUT /v1/buyer/unifiedtags/async

Tags V3 doesn't provide the functionality to update tags in bulk. To update a tag, use the endpoints:

PUT /v3/buyer/tags/directtags/{id}

PUT /v3/buyer/tags/rtbtags/{id}

Update a direct tag by tag ID.

Update an RTB tag by tag ID.

PUT /v1/buyer/unifiedtags/{uuid}/activationstatus

The new endpoints only accept tag IDs. To update a tag's active status, use the endpoints:

PUT /v3/buyer/tags/directtags/{id}/active

PUT /v3/buyer/tags/rtbtags/{id}/active

Update a direct tag’s active status by tag ID.

Update an RTB tag’s active status by tag ID.

PUT /v1/buyer/unifiedtags/activationstatus/async

Tags V3 doesn't provide the functionality to update tags in bulk. To update a tag's active status, use the endpoints:

PUT /v3/buyer/tags/directtags/{id}/active

PUT /v3/buyer/tags/rtbtags/{id}/active

Update a direct tag’s active status by tag ID.

Update an RTB tag’s active status by tag ID.

PUT /v1/buyer/unifiedtags/{uuid}/pausestatus

The new endpoints only accept tag IDs. You can pause only direct tags. To update a direct tag's pause status, use the endpoint:

PUT /v3/buyer/tags/directtags/{id}/paused

Update a direct tag’s pause status by tag ID.

PUT /v1/buyer/unifiedtags/pausestatus/async

Tags V3 doesn't provide the functionality to update tags in bulk. You can pause only direct tags. To update a direct tag's pause status, use the endpoint:

PUT /v3/buyer/tags/directtags/{id}/paused

Update a direct tag’s pause status by tag ID.

DELETE /v1/buyer/unifiedtags/{uuid}/destinationurl

The new endpoints only accept tag IDs. Tags V3 can accept multiple destination URLs. To delete a tag's destination URLs, use the endpoints with empty destinationUrl:

PUT /v3/buyer/tags/directtags/{id}/destinationurls

PUT /v3/buyer/tags/rtbtags/{id}/destinationurls

Update a direct tag’s destination URLs by tag ID.

Update an RTB tag's destination URLs by tag ID.

PUT /v1/buyer/unifiedtags/{uuid}/destinationurl

The new endpoints only accept tag IDs. Tags V3 can accept multiple destination URLs. To update a tag's destination URLs, use the endpoints:

PUT /v3/buyer/tags/directtags/{id}/destinationurls

PUT /v3/buyer/tags/rtbtags/{id}/destinationurls

Update a direct tag’s destination URLs by tag ID.

Update an RTB tag's destination URLs by tag ID.

PUT /v1/buyer/unifiedtags/destinationurls/async

PUT /v3/buyer/tags/directtags/{id}/destinationurls

PUT /v3/buyer/tags/rtbtags/{id}/destinationurls

Update a direct tag’s destination URLs by tag ID.

Update an RTB tag's destination URLs by tag ID.

PUT /v1/buyer/unifiedtags/trackingpixels/async

PUT /v3/buyer/tags/directtags/{id}/trackingpixels

PUT /v3/buyer/tags/rtbtags/{id}/trackingpixels

Update a direct tag’s tracking pixels by tag ID.

Update an RTB tag’s tracking pixels by tag ID.

PUT /v1/buyer/unifiedtags/externalscripts/async

PUT /v3/buyer/tags/directtags/{id}/externalscripts

PUT /v3/buyer/tags/rtbtags/{id}/externalscripts

Update a direct tag’s external scripts by tag ID.

Update an RTB tag’s external scripts by tag ID.

PUT /v1/buyer/unifiedtags/{uuid}/ad

The new endpoints only accept tag IDs. To update a tag's ad, use the endpoints:

PUT /v3/tags/directtags/{id}/ad

PUT /v3/tags/rtbtags/{id}/ad

Update a direct tag’s ad by tag ID.

Update an RTB tag’s ad by tag ID.

PUT /v1/buyer/unifiedtags/{uuid}/lineitem

The new endpoints only accept tag IDs. You can update only the line items of direct tags. To update a line item of a direct tag, use the endpoint:

PUT /v3/buyer/tags/directtags/{id}/lineitem

Update a direct tag’s line item by tag ID.

PUT /v1/buyer/unifiedtags/{uuid}/name

The new endpoints only accept tag IDs. To update a tag name, use the endpoints:

PUT /v3/buyer/tags/directtags/{id}

PUT /v3/buyer/tags/rtbtags/{id}

PUT /v3/buyer/tags/directtags/{id}/settings

PUT /v3/buyer/tags/rtbtags/{id}/settings

Update a direct tag by tag ID.

Update an RTB tag by tag ID.

PUT /v1/buyer/unifiedtags/{uuid}/servingproperties

The new endpoints only accept tag IDs. To update a tag's settings, use the endpoints:

PUT /v3/buyer/tags/directtags/{id}/settings

PUT /v3/buyer/tags/rtbtags/{id}/settings

Update a direct tag's settings by tag ID.

Update an RTB tag's settings by tag ID.

DELETE /v1/buyer/unifiedtags/{uuid}/trackingpixels

POST /v1/buyer/unifiedtags/{uuid}/trackingpixels

The new endpoints only accept tag IDs. Tags V3 can accept multiple tracking pixels. To update a tag's tracking pixels, use the endpoints:

PUT /v3/buyer/tags/directtags/{id}/trackingpixels

PUT /v3/buyer/tags/rtbtags/{id}/trackingpixels

Update a direct tag’s tracking pixels by tag ID.

Update an RTB tag’s tracking pixels by tag ID.

DELETE /v1/buyer/unifiedtags/{uuid}/externalscripts

PUT /v1/buyer/unifiedtags/{uuid}/externalscripts

The new endpoints only accept tag IDs. Tags V3 can accept multiple external scripts. To update a tag's external scripts, use the endpoints:

PUT /v3/buyer/tags/directtags/{id}/externalscripts

PUT /v3/buyer/tags/rtbtags/{id}/externalscripts

Update a direct tag’s external scripts by tag ID.

Update an RTB tag’s external scripts by tag ID.

GET /v1/buyer/unifiedtags/{uuid}/script

The new endpoints only accept tag IDs. To retrieve a direct tag's script, use the endpoint:

GET /v3/buyer/tags/directtags/{id}/script

Retrieve a direct tag's script by tag ID.

POST /v1/buyer/unifiedtags/scripts

The new endpoints only accept tag IDs. To retrieve a direct tag's script, use the endpoint:

GET /v3/buyer/tags/directtags/{id}/script

Retrieve a direct tag's script by tag ID.

POST /v1/buyer/unifiedtags/grouped/scripts

The new endpoints only accept tag IDs. To retrieve a direct tag's script, use the endpoint:

GET /v3/buyer/tags/directtags/{id}/script

Retrieve a direct tag's script by tag ID.

GET /v1/buyer/unifiedtags/operation/{uuid}

This endpoint is no longer relevant because Tags V3 doesn't support most of the previous bulk endpoints.

GET /v1/buyer/unifiedtags/create-operation/{uuid}

This endpoint is no longer relevant because Tags V3 doesn't support most of the previous bulk endpoints.

New Features Introduced With Tags V3

  • Endpoint categorization based on the line item type, separating direct and RTB tags. This makes tag creation easier, because the request body now contains only the parameters that apply to either direct or RTB tags.

  • ClockNumber parameter for RTB tags. A clock number is a unique alphanumeric number that identifies a video ad and its source. It is used to ensure that a video ad complies with the requirements of UK broadcasters detailed in the UK Codes of Advertising.

  • Possibility to synchronize the tag name with the ad name using the updateName flag. This flag can be used to ensure that the tag name will always reflect the ad assigned to it.

Breaking Changes

See the new authorization scopes as well as request samples and field parameters that change when migrating from Unified Tags (V1) to Tags V3.

Authorization

To make API requests to Tags V3, you need a valid bearer token with appropriate scopes:

Previous Scopes

New Scopes

https://api.adform.com/scope/buyer.unified.tags: Yields full access to the API.

https://api.adform.com/scope/buyer.unified.tags.readonly: Yields read-only access to the API.

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.

For more information about authorizing with Adform APIs, see the Authorization Guide.

Create Tags

Unified Tags endpoint POST /v1/buyer/unifiedtags is replaced by Tags V3 endpoints POST /v3/buyer/tags/directtags and POST /v3/buyer/tags/rtbtags. Use the new endpoints to create a new direct or RTB tag. See the changes in the request body and the changed parameter described below.

Request Body Examples and Parameter

Unified Tags POST Request Body Example

{
  "campaignId": 0,
  "adUuid": "string",
  "lineItemId": 0,
  "name": "string"
}

Tags V3 POST Request Body Example for Direct and RTB Tags

{
  "campaignId": 2532,
  "adUuid": "ee45201b-d485-45e9-a67c-ade88248043c",
  "baseLineItemId": 867456,
  "name": "Red sneakers 100x100"
}

Tag V3 Create Tag Parameter

Name

Required or Optional

Description

Direct or RTB

Example Value

Type

baseLineItemId

Required

The naming has changed from lineItemId used in Unified Tags to baseLineItemId. The usage remains unchanged.

Both

867456

Integer

Update Tags

Unified Tags endpoint PUT /v1/buyer/unifiedtags is replaced by Tags V3 endpoints PUT /v3/buyer/tags/directtags/{id} and PUT /v3/buyer/tags/rtbtags/{id}. Use the new endpoints to update various tag parameters. However, Tags V3 doesn't provide httpsEnabled and universalId parameters. See the changes in the request body and the new or changed parameters described below.

Request Body Examples and Parameters

Unified Tags PUT Request Body Example

{
  "uuid": "string",
  "legacyId": 0,
  "campaignId": 0,
  "ad": {
    "uuid": "string",
    "type": "banner"
  },
  "lineItemId": 0,
  "name": "string",
  "httpsEnabled": true,
  "adNoticeEnabled": true,
  "servingMethod": "impressions",
  "tagFormat": "javascriptDefault",
  "universalId": "string",
  "active": true,
  "paused": true,
  "createdAt": "2024-02-22T08:32:46.416Z",
  "updatedAt": "2024-02-22T08:32:46.416Z",
  "destinationUrls": [
    {
      "tagMember": {
        "rotatorMemberId": "string",
        "scheduleMemberId": "string",
        "innerBannerId": "string"
      },
      "destinationUrl": {
        "value": "string",
        "type": "append"
      }
    }
  ],
  "trackingPixels": [
    {
      "tagMember": {
        "rotatorMemberId": "string",
        "scheduleMemberId": "string",
        "innerBannerId": "string"
      },
      "impressionPixels": [
        "string"
      ],
      "clickPixels": [
        "string"
      ],
      "eventPixels": [
        {
          "eventId": 0,
          "value": "string"
        }
      ]
    }
  ],
  "externalScripts": [
    {
      "source": "string",
      "scriptPosition": "before",
      "type": "unknown"
    }
  ],
  "sentDate": "2024-02-22T08:32:46.416Z"
}

Tags V3 PUT Request Body Example for Direct Tags

{
  "active": true,
  "paused": true,
  "settings": {
    "format": "javascriptDefault",
    "servingMethod": "impressions",
    "adNoticeEnabled": true,
    "name": "Red sneakers 100x100"
  },
  "destinationUrls": [
    {
      "tagMember": {
        "rotatorMemberId": "c47bd8c1-ef0c-47fb-bc47-2582e8860f64",
        "scheduleMemberId": "53817a1c-7b1a-4a06-8c5d-84797e548107",
        "innerBannerId": "fb199995-5b98-4517-90d9-b2ef2900433a"
      },
      "value": "https://www.adform.com",
      "type": "replace"
    }
  ],
  "trackingPixels": [
    {
      "tagMember": {
        "rotatorMemberId": "c47bd8c1-ef0c-47fb-bc47-2582e8860f64",
        "scheduleMemberId": "53817a1c-7b1a-4a06-8c5d-84797e548107",
        "innerBannerId": "fb199995-5b98-4517-90d9-b2ef2900433a"
      },
      "impressionPixels": [
        "https://www.adform.com"
      ],
      "clickPixels": [
        "https://www.adform.com"
      ],
      "eventPixels": [
        {
          "value": "https://www.adform.com",
          "eventId": 25
        }
      ]
    }
  ],
  "externalScripts": [
    {
      "source": "https://www.adform.com",
      "scriptPosition": "before",
      "type": "unknown"
    }
  ]
}

Tags V3 PUT Request Body Example for RTB Tags

{
  "active": true,
  "settings": {
    "adNoticeEnabled": true,
    "name": "Red sneakers 100x100",
    "clockNumber": "AAA/BBBB123/456"
  },
  "destinationUrls": [
    {
      "tagMember": {
        "rotatorMemberId": "c47bd8c1-ef0c-47fb-bc47-2582e8860f64",
        "scheduleMemberId": "53817a1c-7b1a-4a06-8c5d-84797e548107",
        "innerBannerId": "fb199995-5b98-4517-90d9-b2ef2900433a"
      },
      "value": "https://www.adform.com",
      "type": "replace"
    }
  ],
  "trackingPixels": [
    {
      "tagMember": {
        "rotatorMemberId": "c47bd8c1-ef0c-47fb-bc47-2582e8860f64",
        "scheduleMemberId": "53817a1c-7b1a-4a06-8c5d-84797e548107",
        "innerBannerId": "fb199995-5b98-4517-90d9-b2ef2900433a"
      },
      "impressionPixels": [
        "https://www.adform.com"
      ],
      "clickPixels": [
        "https://www.adform.com"
      ],
      "eventPixels": [
        {
          "value": "https://www.adform.com",
          "eventId": 25
        }
      ]
    }
  ],
  "externalScripts": [
    {
      "source": "https://www.adform.com",
      "scriptPosition": "before",
      "type": "unknown"
    }
  ]
}

Tag V3 Update Tag Parameters

Name

Required or Optional

Description

Direct or RTB

Example Value

Type

settings

Required

settings define parameters related to the configuration and display of an ad.

Previously, Unified Tags didn't have a settings parameter because tagFormat, servingMethod, adNoticeEnable and name were defined separately, while clockNumber didn’t exist.

Now direct tag settings include format, servingMethod, adNoticeEnabled, and name, while RTB settings include adNoticeEnabled, name, and clockNumber.

Both

Direct:

"settings": {
    "format": "javascriptDefault",
    "servingMethod": "impressions",
    "adNoticeEnabled": true,
    "name": "Red sneakers 100x100"
  }

RTB:

"settings": {
    "adNoticeEnabled": true,
    "name": "Red sneakers 100x100",
    "clockNumber": "AAA/BBBB123/456"
  }

Object

format

Required

The naming has changed from tagFormat in Unified Tags to format. The usage remains unchanged.

Direct

javascriptDefault

Enum

destinationUrls

Optional

Now destinationUrls don't have a destinationUrl object inside. The parameters of this object have been moved to destinationUrls.

Both

 
"destinationUrls": [
    {
      "tagMember": {
        "rotatorMemberId": "c47bd8c1-ef0c-47fb-bc47-2582e8860f64",
        "scheduleMemberId": "53817a1c-7b1a-4a06-8c5d-84797e548107",
        "innerBannerId": "fb199995-5b98-4517-90d9-b2ef2900433a"
      },
      "value": "https://www.adform.com",
      "type": "replace"
    }
  ]

Object

clockNumber

Optional

A new parameter added to Tags V3. A clock number is used to ensure that a video ad complies with the requirements set in the UK Codes of Advertising.

RTB

AAA/BBBB123/456

String

Retrieve Tags

Unified Tags endpoint GET /v1/buyer/unifiedtags/single/{id} is replaced by Tags V3 endpoints GET /v3/buyer/tags/directtags/{id} and GET /v3/buyer/tags/rtbtags/{id}. Use the new endpoints to retrieve a tag by tag ID. However, Tags V3 doesn't provide httpsEnabled and universalId parameters. See the changes in the response body and the new or changed parameters described below.

Response Body Examples and Parameters

Unified Tags GET Response Body Example

{
  "uuid": "string",
  "legacyId": 0,
  "campaignId": 0,
  "ad": {
    "uuid": "string",
    "type": "banner"
  },
  "lineItemId": 0,
  "name": "string",
  "httpsEnabled": true,
  "adNoticeEnabled": true,
  "servingMethod": "impressions",
  "tagFormat": "javascriptDefault",
  "universalId": "string",
  "active": true,
  "paused": true,
  "createdAt": "2024-02-26T10:54:16.669Z",
  "updatedAt": "2024-02-26T10:54:16.669Z",
  "destinationUrls": [
    {
      "tagMember": {
        "rotatorMemberId": "string",
        "scheduleMemberId": "string",
        "innerBannerId": "string"
      },
      "destinationUrl": {
        "value": "string",
        "type": "append"
      }
    }
  ],
  "trackingPixels": [
    {
      "tagMember": {
        "rotatorMemberId": "string",
        "scheduleMemberId": "string",
        "innerBannerId": "string"
      },
      "impressionPixels": [
        "string"
      ],
      "clickPixels": [
        "string"
      ],
      "eventPixels": [
        {
          "eventId": 0,
          "value": "string"
        }
      ]
    }
  ],
  "externalScripts": [
    {
      "source": "string",
      "scriptPosition": "before",
      "type": "unknown"
    }
  ],
  "sentDate": "2024-02-26T10:54:16.669Z"
}

Tags V3 GET Response Body Example for Direct Tags

{
  "id": 1957673,
  "uuid": "bd755e28-ece3-42f0-b65a-5fae71de5e48",
  "campaignId": 892879,
  "adId": {
    "id": {
      "uuid": "9a612de4-fd73-489c-ace1-181c422bba0e",
      "id": 18999575
    },
    "adType": "creative"
  },
  "baseLineItemId": 1774860,
  "active": true,
  "paused": false,
  "settings": {
    "format": "javascriptDefault",
    "servingMethod": "impressions",
    "adNoticeEnabled": true,
    "name": "Green shirt 150x200"
  },
  "sentAt": "2023-03-20T08:27:27.748Z",
  "sentBy": "b21633ee-ad99-45d4-a6cb-adb217bcf0ee",
  "createdAt": "2023-03-20T08:25:23.251Z",
  "createdBy": "b21633ee-ad99-45d4-a6cb-adb217bcf0ee",
  "updatedAt": "2023-03-20T08:27:27.748Z",
  "updatedBy": "b21633ee-ad99-45d4-a6cb-adb217bcf0ee",
  "version": 1,
  "destinationUrls": [
    {
      "tagMember": {
        "rotatorMemberId": "65c8b7ce-1a8b-4e18-988b-beb6e426a7c1",
        "scheduleMemberId": "2458a9f6-1401-4efd-8b96-9bfe707a9235",
        "innerBannerId": "f0baa8d7-833d-4624-b875-57beb8b2d12d"
      },
      "value": "https://www.adform.com",
      "type": "replace"
    }
  ],
  "trackingPixels": [
    {
      "tagMember": {
        "rotatorMemberId": "424c3ead-e6cc-44e6-80d1-e278804bdc42",
        "scheduleMemberId": "efd7cd4c-df69-44df-bc51-a0b3df6f39fc",
        "innerBannerId": "fd06bd8c-edc1-4118-9e08-87a4695a89be"
      },
      "impressionPixels": [
        "https://www.adform.com"
      ],
      "clickPixels": [
        "https://www.adform.com"
      ],
      "eventPixels": [
        {
          "value": "https://www.adform.com",
          "eventId": 25
        }
      ]
    }
  ],
  "externalScripts": [
    {
      "source": "someScriptSource",
      "scriptPosition": "before",
      "type": "unknown"
    }
  ]
}

Tags V3 GET Response Body Example for RTB Tags

{
  "id": 1956869,
  "uuid": "65c144ca-7ea5-4987-bb1b-f9d5826a59e2",
  "campaignId": 890650,
  "adId": {
    "id": {
      "uuid": "8fd93c5f-9039-42b4-b282-50203b3a0bce",
      "id": 18994913
    },
    "adType": "creative"
  },
  "baseLineItemId": 1770841,
  "active": true,
  "settings": {
    "adNoticeEnabled": true,
    "name": "Red sneakers 100x100",
    "clockNumber": "AAA/BBBB123/456"
  },
  "sentAt": "2023-03-20T08:27:27.748Z",
  "sentBy": "b21633ee-ad99-45d4-a6cb-adb217bcf0ee",
  "createdAt": "2023-03-20T08:25:23.251Z",
  "createdBy": "b21633ee-ad99-45d4-a6cb-adb217bcf0ee",
  "updatedAt": "2023-03-20T08:27:27.748Z",
  "updatedBy": "b21633ee-ad99-45d4-a6cb-adb217bcf0ee",
  "version": 1,
  "destinationUrls": [
    {
      "tagMember": {
        "rotatorMemberId": "9aad2304-af22-4e5a-b2ac-9b4f1b303bb4",
        "scheduleMemberId": "ea097ea2-96f6-417c-b3ed-9f09e483ed38",
        "innerBannerId": "f5e8f756-b74a-429f-812c-4628e8ad346d"
      },
      "value": "https://www.adform.com",
      "type": "replace"
    }
  ],
  "trackingPixels": [
    {
      "tagMember": {
        "rotatorMemberId": "80eb071e-9b03-4f8f-9572-572c125ac849",
        "scheduleMemberId": "cb2b3680-9076-47f0-9e8d-a1fa56cbf75d",
        "innerBannerId": "42c346b4-2843-477e-bfaf-dd0120a04aec"
      },
      "impressionPixels": [
        "https://www.adform.com"
      ],
      "clickPixels": [
        "https://www.adform.com"
      ],
      "eventPixels": [
        {
          "value": "https://www.adform.com",
          "eventId": 25
        }
      ]
    }
  ],
  "externalScripts": [
    {
      "source": "someScriptSource",
      "scriptPosition": "before",
      "type": "unknown"
    }
  ]
}

Tags V3 Retrieve Tag Parameters

Name

Required or Optional

Description

Direct or RTB

Example Value

Type

adId

Required

Previously, Unified Tags had an ad object instead of adId.

Now adId includes adType and id objects, with id containing uuid and id.

Both

 
"adId": {
    "id": {
      "uuid": "9a612de4-fd73-489c-ace1-181c422bba0e",
      "id": 18999575
    },
    "adType": "creative"
  }

Object

id

Required

The id object is a component of the adId object, containing ad id and uuid.

Both

 
"id": {
      "uuid": "9a612de4-fd73-489c-ace1-181c422bba0e",
      "id": 18999575
    }

Object

baseLineItemId

Required

The naming has changed from lineItemId used in Unified Tags to baseLineItemId. The usage remains unchanged.

Both

1774860

Integer

adType

Required

The naming has changed from type used in Unified Tags to adType. The usage remains unchanged.

Both

creative

Enum

settings

Required

settings define parameters related to the configuration and display of an ad.

Previously, Unified Tags didn't have a settings parameter because tagFormat, servingMethod, adNoticeEnable and name were defined separately, while clockNumber didn’t exist.

Now direct tag settings include format, servingMethod, adNoticeEnabled, and name, while RTB settings include adNoticeEnabled, name, and clockNumber.

Both

Direct:

"settings": {
    "format": "javascriptDefault",
    "servingMethod": "impressions",
    "adNoticeEnabled": true,
    "name": "Red sneakers 100x100"
  }

RTB:

"settings": {
    "adNoticeEnabled": true,
    "name": "Red sneakers 100x100",
    "clockNumber": "AAA/BBBB123/456"
  }

Object

sentAt

Optional

A new property added to Tags V3. Sent date and time in ISO 8601 format.

Both

2023-03-20T08:27:27.748Z

String

sentBy

Optional

A new property added to Tags V3. The UUID of the user profile that last sent the tag.

Both

b21633ee-ad99-45d4-a6cb-adb217bcf0ee

String

createdBy

Required

A new property added to Tags V3. The UUID of a user profile that created the tag.

Both

b21633ee-ad99-45d4-a6cb-adb217bcf0ee

String

updatedBy

Required

A new property added to Tags V3. The UUID of the user profile that last updated the tag.

Both

b21633ee-ad99-45d4-a6cb-adb217bcf0ee

String

version

Required

A new property added to Tags V3. The tag version.

Both

1

Integer

destinationUrls

Required

Now destinationUrls don't have a destinationUrl object inside. The parameters of this object have been moved to destinationUrls.

Both

 
"destinationUrls": [
    {
      "tagMember": {
        "rotatorMemberId": "c47bd8c1-ef0c-47fb-bc47-2582e8860f64",
        "scheduleMemberId": "53817a1c-7b1a-4a06-8c5d-84797e548107",
        "innerBannerId": "fb199995-5b98-4517-90d9-b2ef2900433a"
      },
      "value": "https://www.adform.com",
      "type": "replace"
    }
  ]

Object

clockNumber

Optional

A new parameter added to Tags V3. A clock number is used to ensure that a video ad complies with the requirements set in the UK Codes of Advertising.

RTB

AAA/BBBB123/456

String

Update Tag's Destination URLs

Unified Tags endpoint PUT /v1/buyer/unifiedtags/{uuid}/destinationurl is replaced by Tags V3 endpoints PUT /v3/buyer/tags/directtags/{id}/destinationurls and PUT /v3/buyer/tags/rtbtags/{id}/destinationurls. Use the new endpoints to update a tag's destinationurl. See the changes in the request body and the new parameters described below.

Request Body Examples and Parameters

Unified Tags Destination URLs PUT Request Body Example

{
  "tagMember": {
    "rotatorMemberId": "string",
    "scheduleMemberId": "string",
    "innerBannerId": "string"
  },
  "url": "string"
}

Tags V3 Destination URLs PUT Request Body Example for Direct and RTB Tags

[
  {
    "tagMember": {
      "rotatorMemberId": "c47bd8c1-ef0c-47fb-bc47-2582e8860f64",
      "scheduleMemberId": "53817a1c-7b1a-4a06-8c5d-84797e548107",
      "innerBannerId": "fb199995-5b98-4517-90d9-b2ef2900433a"
    },
    "value": "https://www.adform.com",
    "type": "replace"
  }
]

Tags V3 Destination URLs Parameters

Name

Required or Optional

Description

Direct or RTB

Example Value

Type

value

Required

A new parameter added to Tags V3. Replaces the previously used url and indicates the destination URL.

Both

https://www.adform.com

String

type

Required

A new parameter added to Tags V3. Indicates the action that you want to perform with the destination URL: replace (add full URL as value) or append (add URL ending as value).

Both

replace

Enum

Replace Direct Tag's Line Items

Unified Tags endpoint PUT /v1/buyer/unifiedtags/{uuid}/lineitem is replaced by Tags V3 endpoint PUT /v3/buyer/tags/directtags/{id}/lineitem. Use the new endpoint to replace the baseLineItemId of a direct tag. See the changes in the request body and the changed parameter described below.

Request Body Examples and Parameter

Unified Tags Line Item PUT Request Body Example

{
  "lineItemId": 0
}

Tags V3 Line Item PUT Request Body Example for Direct Tags

{
  "baseLineItemId": 1774860
}

Tags V3 Line Item Parameter

Name

Required or Optional

Description

Direct or RTB

Example Value

Type

baseLineItemId

Required

The naming has changed from lineItemId used in Unified Tags to baseLineItemId. The usage remains unchanged.

Direct

1774860

Integer

Update Tag's Settings

Unified Tags endpoints PUT /v1/buyer/unifiedtags/{uuid}/servingproperties and PUT /v1/buyer/unifiedtags/{uuid}/name are replaced by Tags V3 endpoints PUT /v3/buyer/tags/rtbtags/{id}/settings and PUT /v3/buyer/tags/directtags/{id}/settings. Use the new endpoints to update the settings of a direct or an RTB tag, including the tag name. However, Tags V3 doesn't provide httpsEnabled parameter. See the changes in the request body and the changed or new parameters described below.

Request Body Examples and Parameters

Unified Tags Serving Properties PUT Request Body Example

{
  "httpsEnabled": true,
  "adNoticeEnabled": true,
  "servingMethod": "impressions",
  "tagFormat": "javascriptDefault"
}

Tags V3 Settings PUT Request Body Example for Direct Tags

{
  "format": "javascriptDefault",
  "servingMethod": "impressions",
  "adNoticeEnabled": true,
  "name": "Red sneakers 100x100"
}

Tags V3 Settings PUT Request Body Example for RTB Tags

{
  "adNoticeEnabled": true,
  "name": "Red sneakers 100x100",
  "clockNumber": "AAA/BBBB123/456"
}

Tags V3 Settings Parameters

Name

Required or Optional

Description

Direct or RTB

Example Value

Type

httpsEnabled

Tags V3 settings endpoints don't have httpsEnabled parameter.

Both

format

Required

The naming has changed from tagFormat in Unified Tags to format. The usage remains unchanged.

Direct

javascriptDefault

Enum

name

Required

Now Tags V3 includes the tag name in settings.

Both

Red sneakers 100x100

String

clockNumber

Optional

A new parameter added to Tags V3. A clock number is used to ensure that a video ad complies with the requirements set in the UK Codes of Advertising.

RTB

AAA/BBBB123/456

String

Replace Tag's Ad

Unified Tags endpoint PUT /v1/buyer/unifiedtags/{uuid}/ad is replaced by Tags V3 endpoints PUT /v3/buyer/tags/rtbtags/{id}/ad and PUT /v3/buyer/tags/directtags/{id}/ad. Use the new endpoints to replace the ad of a direct or an RTB tag. See the changes in the request body and the new parameter described below.

Request Body Examples and Parameter

Unified Tags Ad PUT Request Body Example

{
  "adUuid": "string"
}

Tags V3 Ad PUT Request Body Example for Direct and RTB Tags

{
  "adUuid": "b41e55c9-17e7-4cbc-bb24-4ced79f45a23",
  "updateName": false
}

Tags V3 Ad Parameter

Name

Required or Optional

Description

Direct or RTB

Example Value

Type

updateName

Optional

A new parameter added to Tags V3. A flag that indicates whether to synchronize the tag name with the name of the new ad. Previously, the tag name could only be updated by calling a separate endpoint.

Both

false

Boolean

Retrieve Tags List

Unified Tags list accepted only tag UUIDs while the Tags V3 endpoint POST /v3/buyer/tags/list is designed to retrieve an array of existing tags based on specified filters. These newly added filters include campaignId, baseLineItemIds, adUuid, active, tagIds, tagUuids, name and type. See the changes in the request body and the new parameters described below.

Request Body Examples and Parameters

Unified Tags List POST Request Body Example

[
"d40543d1-65bd-4fc5-9ec6-fb4cbb32da30", 
"d40543d1-65bd-4fc5-9ec6-fb4cbb32da40"
]

Tags V3 List POST Request Body Example

{
  "campaignId": 2532,
  "baseLineItemIds": [
    7745
  ],
  "adUuid": "a0c1fd34-4450-4341-bfba-93c81960cb17",
  "active": true,
  "tagIds": [
    123,
    5321
  ],
  "tagUuids": [
    "d40543d1-65bd-4fc5-9ec6-fb4cbb32da30"
  ],
  "name": "Red sneakers 100x100",
  "type": "direct"
}

Tags V3 List Parameters

Name

Required or Optional

Description

Direct or RTB

Example Value

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 direct or RTB

Both

direct

Enum

Retrieve Direct Tag's Script

Unified Tags endpoint GET /v1/buyer/unifiedtags/{uuid}/script is replaced by Tags V3 endpoint GET /v3/buyer/tags/directtags/{id}/script. Use the new endpoint to retrieve a direct tag's script by tag ID. You can also provide value for gdprEnabled query parameter to enable or disable GDPR values in tag’s script URLs when calling this endpoint.

Name

Required or Optional

Description

Direct or RTB

Example Value

Type

gdprEnabled

Optional

A value that indicates whether to add GDPR values to direct tag’s script URLs.

Direct

false

Boolean

However, Tags V3 doesn't return lightScript, campaignId and mediaId properties like Unified Tags did with POST /v1/buyer/unifiedtags/grouped/scripts and POST /v1/buyer/unifiedtags/scripts endpoints. In Tags V3, script is the same as Lightscript was in Unified Tags. In addition, Tags V3 direct tag script endpoint accepts and returns direct tag scripts for a single tag ID at a time. See the changes in the response body and the changes or new parameters described below.

Response Body Examples and Parameters

Unified Tags Direct Tag Script GET /v1/buyer/unifiedtags/{uuid}/script Response Body Example

{
  "uuid": "0000000-0000-0000-0000-000000000000",
  "script": "------------------------------------------------------------------------------------------------------------------------
Client: Client
Campaign: Direct campaign 
Campaign ID: CAMPAIGNID
Network: test (Media)
Media: test
User: user

Information about implementing Adform tags can be found at the address: http://creative.adform.com/support/documentation/third-party-tags/adform-tags-as-3rd-party *
------------------------------------------------------------------------------------------------------------------------

 

************************************************************************************************************************
Tag 1. Direct_tags_integration_test_2024-05-09 05:02:41Z (Line Item: Direct LI, Size: 300x250, Type: In-Stream)  
************************************************************************************************************************

Tag Comment 1: test_comment_1
Tag Comment 2: test_comment_2

Serving method: In-Stream video VAST XML:

VAST 2.0: https://track.d1.adform.zone/serving/videoad/?bn=123456&v=2&ord=[timestamp]
VAST 3.0: https://track.d1.adform.zone/serving/videoad/?bn=123456&v=3&ord=[timestamp]
VAST 4.0: https://track.d1.adform.zone/serving/videoad/?bn=123456&v=40&ord=[timestamp]
VAST 4.1: https://track.d1.adform.zone/serving/videoad/?bn=123456&v=41&ord=[timestamp]
VAST 4.2: https://track.d1.adform.zone/serving/videoad/?bn=123456&v=42&ord=[timestamp]

Note: Replace \"[timestamp]\" in the tag(s) above with your timestamp/random number variable.
"
}

Unified Tags Direct Tag Script POST /v1/buyer/unifiedtags/scripts Response Body Example

[
  {
    "uuid": "0000000-0000-0000-0000-000000000000",
    "script": "------------------------------------------------------------------------------------------------------------------------
Client: Client
Campaign: Direct campaign 
Campaign ID: CAMPAIGNID
Network: test (Media)
Media: test
User: user

Information about implementing Adform tags can be found at the address: http://creative.adform.com/support/documentation/third-party-tags/adform-tags-as-3rd-party *
------------------------------------------------------------------------------------------------------------------------

 

************************************************************************************************************************
Tag 1. Direct_tags_integration_test_2024-05-09 05:02:45Z_updated (Line Item: Direct LI 2, Size: 300x250, Type: In-Stream)  
************************************************************************************************************************


Serving method: In-Stream video VAST XML:

VAST 2.0: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=2&ord=[timestamp]
VAST 3.0: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=3&ord=[timestamp]
VAST 4.0: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=40&ord=[timestamp]
VAST 4.1: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=41&ord=[timestamp]
VAST 4.2: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=42&ord=[timestamp]

Note: Replace \"[timestamp]\" in the tag(s) above with your timestamp/random number variable.
",
    "lightScript": "

VAST 2.0: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=2&ord=[timestamp]
VAST 3.0: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=3&ord=[timestamp]
VAST 4.0: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=40&ord=[timestamp]
VAST 4.1: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=41&ord=[timestamp]
VAST 4.2: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=42&ord=[timestamp]

Note: Replace \"[timestamp]\" in the tag(s) above with your timestamp/random number variable."
  }
]

Unified Tags Direct Tag Script POST /v1/buyer/unifiedtags/grouped/scripts Response Body Example

[
  {
    "campaignId": 12345,
    "mediaId": 123456,
    "uuids": [
      "0000000-0000-0000-0000-000000000000"
    ],
    "script": "------------------------------------------------------------------------------------------------------------------------
Client: Client
Campaign: Direct campaign 
Campaign ID: CAMPAIGNID
Network: test (Media)
Media: test
User: user

Information about implementing Adform tags can be found at the address: http://creative.adform.com/support/documentation/third-party-tags/adform-tags-as-3rd-party *
------------------------------------------------------------------------------------------------------------------------

 

************************************************************************************************************************
Tag 1. Direct_tags_integration_test_2024-05-09 05:02:45Z_updated (Line Item: Direct LI 2, Size: 300x250, Type: In-Stream)  
************************************************************************************************************************


Serving method: In-Stream video VAST XML:

VAST 2.0: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=2&ord=[timestamp]
VAST 3.0: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=3&ord=[timestamp]
VAST 4.0: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=40&ord=[timestamp]
VAST 4.1: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=41&ord=[timestamp]
VAST 4.2: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=42&ord=[timestamp]

Note: Replace \"[timestamp]\" in the tag(s) above with your timestamp/random number variable.
"
  }
]

Tags V3 Direct Tag Script GET Response Body Example

{
  "script": "Serving method: In-Stream video VAST XML:

VAST 2.0: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=2&ord=[timestamp]
VAST 3.0: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=3&ord=[timestamp]
VAST 4.0: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=40&ord=[timestamp]
VAST 4.1: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=41&ord=[timestamp]
VAST 4.2: https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=42&ord=[timestamp]

Banner preview: https://www.d1.adform.zone/BannerTags/Views/Test/Test.aspx?id=1234567
Note: Replace \"[timestamp]\" in the tag(s) above with your timestamp/random number variable.",
  "urls": [
    {
      "url": "https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=2&ord=[timestamp]",
      "type": "vast20"
    },
    {
      "url": "https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=3&ord=[timestamp]",
      "type": "vast30"
    },
    {
      "url": "https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=40&ord=[timestamp]",
      "type": "vast40"
    },
    {
      "url": "https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=41&ord=[timestamp]",
      "type": "vast41"
    },
    {
      "url": "https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=42&ord=[timestamp]",
      "type": "vast42"
    },
    {
      "url": "https://www.d1.adform.zone/BannerTags/Views/Test/Test.aspx?id=1234567",
      "type": "preview"
    }
  ]
}

Tags V3 Direct Tags Script Parameters

Name

Required or Optional

Description

Direct or RTB

Example Value

Type

urls

Required

urls contain a list of URLs from direct tag script

Direct

 
"urls": [
    {
      "url": "https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=2&ord=[timestamp]",
      "type": "vast20"
    },
    {
      "url": "https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=3&ord=[timestamp]",
      "type": "vast30"
    },
    {
      "url": "https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=40&ord=[timestamp]",
      "type": "vast40"
    },
    {
      "url": "https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=41&ord=[timestamp]",
      "type": "vast41"
    },
    {
      "url": "https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=42&ord=[timestamp]",
      "type": "vast42"
    },
    {
      "url": "https://www.d1.adform.zone/BannerTags/Views/Test/Test.aspx?id=1234567",
      "type": "preview"
    }
  ]

Array

url

Required

A URL string from direct tag script

Direct

https://track.d1.adform.zone/serving/videoad/?bn=1234567&v=42&ord=[timestamp]

String

type

Required

A direct tag script type

Direct

vast42

Enum

sequenceNumber

Optional

A sequence number of a synchronized tag member within the full script

Direct

1

Integer

Was this article helpful?

/
How we can make it better?

Thank you for your feedback!