Automated Tagging API

Introduction & Base URL

The Automated Tagging API enables mutual clients of ad servers and IAS to automatically wrap their display and video ad server tags with IAS's Open Web product, without leaving the ad server platform. This reduces the time it takes to launch a new campaign by removing the manual file sharing process between systems.

As part of the Automated Tagging API, IAS has an "Automated Tag" that:

• Enables the ad server user to control enabling and disabling of the IAS service.

• Eliminates the need for re-trafficking if the campaign is already live and the client wants to enable IAS.

• Eliminates re-trafficking if the client adds or removes new creatives.

• Enables ad servers to record ads IAS blocks and to display this information in your dashboard.

For DSP partners, the Automated Tagging API shares pre-bid segments that align with clients’ IAS campaign settings. This improves user experience and saves time by eliminating the need to manually set up pre-bid configurations.

Base URL

For all production API calls, use the following Base URL:

Authentication

GET your OAuth2 token so you can all the API securely. See a template cURL command in the code example section to the right that you can copy and configure with your credentials.

Example cURL template:

The Authorization token remains valid for 8 hours.

Request Body:

Authorization Response

200 - Success

If accepted, the API returns a JSON object with your token and JTI, as shown in the example response below:

Errors

403 - Forbidden

The following code and data returns if there is a problem with the token.

Ad Server Integration: Ad Server Tags with IAS Tags

Before You Begin

Work with your IAS representative to determine the format in which you want your ad server, DSP, or SSP macro values to be for display tags. IAS needs to know this first to configure your Get Wrapped Tag endpoint. A successful response from this endpoint includes the tag value of the tagWrapped object like in the example response to the right. The tag value is the automated tag, and is a URL that loads JavaScript to measure impression data. For display tags, IAS appends your macros as query parameters to this URL.

For video tags, the tag value is a URL like this example:

https://unified.adsafeprotected.com/vast/fwjsvid/st/12/3/skeleton.js?&blockedAdTracking={adserver_ping_URL}.

Format Tags with IAS Display Tags

Follow these steps to format your ad server tag with IAS display tags:

1. Work with your IAS representative to determine the format you want your DSP or SSP macro values to be. IAS needs to know this format to correctly add them as query parameters to the tag response.

2. In your ad server tag, create a <div> container element that holds the creative, has a discoverable id, and has CSS styling like in the example ad server tag to the right. IAS recommends you dynamically build the <div> container on tag load, because if you build the tag with the script data attributes already present in the text body, then switching between monitoring and blocking will require you to rebuild and retraffick.

3. Set style= to "visibility: hidden" for blocking, or "visibility: unhidden" for monitoring.

4. Below the container <div>, add a <script> element with the tag URL as the source, and four IAS data attributes as shown in the example with code comments to the right. If you are configuring an ad for monitoring only, you do not need to format any further.

5. For blocking only, on the window context, add a callback function as a global variable with a unique name that matches the data-ias-callback attribute like in in window call back code example to the right. The IAS blocking decisioning service invokes: {unique-callback-name}({block: true}) to indicate it blocked the ad. If IAS decides to not block an add, the decisioning service invokes: {unique-callback-name}({block: false}), and your ad server now has ownership on the decision to block or not.

6. Optionally, to unhide the ad, you can set: container.style.visibility = "".

7. If IAS blocks an ad, see the Your Choices After IAS Blocks an Ad section below.

Example Ad Server Tag with IAS Display:

Format Tags with IAS Video Tags

This is this an IAS URL example you get in the tag value for video: https://unified.adsafeprotected.com/vast/fwjsvid/st/12/3/skeleton.js?&blockedAdTracking={adserver_ping_URL}&originalVast={adserver_VAST_URL} Follow these steps to format your ad server tag with IAS video tags:

1. In the URL value, replace {adserver_ping_URL} with the URL IAS should call to block. You receive a ping to this URL every time IAS determines to block. You can use this ping to count the number of ads blocked for this placement.

2. If the tag has a VPAID wrapper, then the wrapper pings the URL. If the tag has VAST-only blocking, then the IAS decisioning service performs a server-to-server ping to the URL. If IAS determines not to block the video ad, then {adserver_ping_URL} does not receive a ping.

Your Choices After IAS Blocks an Ad

If IAS blocks an ad, determine what should happen next. These are options you can choose:

• Do nothing. The creative remains hidden indefinitely.

• Remove the container element from the DOM carefully because it may cause unexpected changes to page layout.

• Erase container contents

  (container.innerHTML = "").

• Load another creative in the container carefully because the container is invisible and contains existing creative code, with these steps:

1. Wipe out container contents with: (container.innerHTML = "").

2. Unhide the container element.

3. Load another creative in the container with asynchronous rendering. If you need document.write, you may need to create an iframe in the container to properly load the other creative.

Put - Link Ad Server Account to IAS Team

Link Ad Server Account to IAS Team. An "IAS team" is the system equivalent to an "ad server account".

Allow customers to link IAS "teams" with their account. After you send a request to this endpoint, the account will be "pending" while it's reviewed, then subsequently approved.

Route

Example:

Headers & Schema

Response

200 - Success

200 - Success Response Example:

Errors

• 400 - Bad request - Internal error on team linking

• 400 - Bad request - Invalid team

• 400 - Bad request - Team not available

Ad Server Requirements

The Ad Server needs to be able to pass to IAS the following:

1. Ad Server account

   • Ad server Account Name (optional)

   • Ad server Account ID (required)

2. Advertiser ID

   • Advertiser Name (optional)

   • Advertiser ID (required)

Put - Link Ad Server Campaign to IAS Campaign

Link Ad Server Campaign to IAS Campaign. Make sure you have successfully mapped an IAS team ID to an ad server account in the prior step (The Link Teams endpoint above).

Call this endpoint to link an IAS campaign with an ad server campaign. If successful, IAS returns a segment response.

IAS recommends calling this endpoint once every 24 hours for each campaign to account for any changes the customer makes in IAS Open Web settings.

Your ad server may not need to link campaigns if it is not connected to a DSP for programmatic buys. This is optional.

Route

Example:

Headers & Schema

Response

200 - Success

Example JSON object response:

Within the API response, you can find the specific details surrounding which segments are properly applied to your advertiser's campaign to best match their Open Web settings. Below are the fields relevant to best optimize a campaign using IAS Pre-bid.

ID If you have integrated the segment data type, this field identifies the segment ID that IAS will apply.

Exclude Negative targeting segments apply only to keyword and URL blacklists. A "true" or "false" value indicates that the segment is positively or negatively targeting segments, respectively.

Channel

The possible values for Channel include all individual segments (Desktop, Mobile Web, Mobile App, and CTV), and "All" and "Web_All":

Category

The specific IAS Pre-bid product for which this segment reflects. Each IAS Pre-bid product is priced separately.

Format

The possible values for Format are:

Errors

• 400 - Bad Request - Missing team-account mapping

• 400 - Bad request - Invalid IAS campaign

• 403 - Unauthorized - This returns a message mentioning authorization is denied.

• 500 - Internal error retrieving prebid information

• 500 - Internal error on campaign linking

Ad Server Requirements

The Ad Sever needs to be able to pass to IAS the following:

1. Ad Server Campaign Name (optional)

2. Ad Server Campaign ID (required)

Post - Send Tags for Wrapping

Send Tags for Wrapping. Send your tags in one call for one or multiple placements. The API automatically ensures correct wrapping with Open Web Monitoring or Open Web Blocking by pulling client-preferred settings and placement details from the Media Partner / Publisher profile.

Route

Include tag information in a JSON object request as shown below:

Headers & Schema

Request Body Schema

Responses

200 - Success

200 - Success Response Example:

Errors

Errors will return a JSON object response body with more information

• 400 - Bad Request

• 403 - Unauthorized

Put - Update Placement Solution

Route

Include tag information in a JSON object request as shown in the example below:

Headers & Schema

Request Body Schema

Responses

200 - Success

200 - Success Response Example:

[ { "id": "7849521", "solution": "BLOCKING", "status": 200, "message": "Placement successfully updated" }, { "id": "4646788", "solution": "MONITORING" }, { "id": "4646785", "solution": "BLOCKING", "status": 401, "message": "Solution not supported for this placement" }, { "id": "181818236", "solution": "BLOCKING", "status": 402, "message": "Placement not found" }, { "id": "696965044", "solution": "MONITORING", "status": 200, "name": "updated_name", "message": "Placement successfully updated" }, { "id": "696965045", "name": "updated_name_1", "status": 200, "message": "Placement successfully updated" }, { "id": "696965046", "solution": "MONITORING", "name": "updated_name_2", "status": 201, "message": "Placement in pending status. Placement name successfully updated" } ] Errors

Errors will return a JSON object response body with more information

• 400 - Bad Request

• 403 - Unauthorized

Get - Get Your Wrapped Tags

A call is limited to one placement ID, and can return one tag per placement. IAS recommends calling this endpoint at least 30 seconds after you submit tags in the previous step. If tags are still not ready after 30 seconds, IAS recommends calling this endpoint no more than once every five minutes to check if your tags are ready.

Route

Parameters

Responses

200 - Success

The examples below show what successful responses looks like for possible statuses.

200 - Success Wrapped Response Example:

{ "status": "WRAPPED", "reason": "Tag wrapping for placementId 20000456 has already been completed.", "tagWrapped": { "tag":"http://fw.adsafeprotected.com/rjss/static.adsafeprotected.com/0/-2/fw-blocking/default/redirection/path/skeleton.js", "dataParameters": "Data to be passed to IAS during ad server response", "keyValues": "Optional. Macros to be appended to the INS tag during export. They will be expanded and passed along to IAS during tag rendering", "solution": "MONITORING|BLOCKING", "blockingAllowed": true|false, "format": "DISPLAY|VIDEO|TRACKING|VIDEOPIXEL|VIDEO_UVT_NON_VPAID" } }

200 - Success (Sample response for UVP with quartiles):

{ "status": "WRAPPED", "reason": "Tag wrapping for placementId 20000456 has already been completed.", "tagWrapped": { "tag":"http://impresionUrl", "dataParameters": "Data to be passed to IAS during ad server response", "keyValues": "Optional. Macros to be appended to the INS tag during export. They will be expanded and passed along to IAS during tag rendering", "solution": "MONITORING", "blockingAllowed": false, "format": "VIDEOPIXEL", "quartiles": { "start": "http://quartileUrl", "firstQuartile": "http://quartileUrl", "midPoint": "http://quartileUrl", "thirdQuartile": "http://quartileUrl", "complete": "http://quartileUrl", "error" : "http://quartileUrl" } } }

200 - Success Pending Response Example:

{ "status": "PENDING", "reasonCode": "UNMAPPED_PUBLISHER|MEDIA_PARTNER_NOT_IN_CAMPAIGN|SOW_NOT_SIGNED", "reason": "Tag wrapping for placementId 2000043334 has been submitted earlier but is not yet complete." }

200 - Success Invalid Response Example:

{ "status": "INVALID", "reason": "This media partner doesn't allow IAS's Multimedia tag on their inventory" }

200 - Success Cancelled Response Example:

{ "status": "CANCELLED", "reason": "Tag wrapping for placementId 2000043334 has been cancelled." }

200 - Success Wrapped Manually Response Example:

{ "status": "WRAPPED_MANUALLY", "reason": "The placement 2000043334 is already built manually" }

Success Response Schema

Errors

Errors will return a JSON object response body with more information.

• 400 - Bad Request

• 403 - Unauthorized

Delete - Cancel Tag Wrapping

Cancel tag wrapping.

Route

Responses

• 204 - Success

Errors

• 400 - Bad Request

• 401 - Unauthorized - Invalid token

• 403 Forbidden - Expired token

Get - Get Ad Server Notifications

Get Ad Server Notifications

Request Route

Parameters

Responses

• 200 - Success

200 - Success Example:

{ "notifications": [ { "ackId": "71a3058b-cdef-4gha-i8j2-k151c5d4f9fe", "objectType": "PLACEMENT", "eventType": "UPDATE", "eventDate": "2020-05-08 12:15:45", "data": { "externalId": "834534221", "solution": "BLOCKING", "adServerAccountIds": ["123", "456"], "iasCampaignId": "456", "blockingAllowed": true, "format": "DISPLAY" } }, { "ackId": "2428e6ed-79dc-4f4d-841f-00e0851e9c4", "objectType": "PLACEMENT", "eventType": "UPDATE", "eventDate": "2020-05-08 12:15:45", "data": { "adServerAccountIds": [ "1315459", "Test Account ID ABC", "555", "testingcmpQA_" ], "solution": "MONITORING", "format": "VIDEO", "externalId": "88088001", "tag": "https://unified.adsafeprotected.com/v2/172802/47695220?mon=47695221&omidPartner=[OMIDPARTNER]&apiframeworks=[APIFRAMEWORKS]&bundleId=[BUNDLEID]&blockedAdTracking=${DC_BLOCKED_AD}&originalVast=${DC_VAST_URL}", "blockingAllowed": false, "iasCampaignId": "172802" } }, { "ackId": "a7375282-7dba-44df-a650-de230940327b", "objectType": "CAMPAIGN", "eventType": "CANCEL", "eventDate": "2020-05-07 12:15:45", "data": { "externalId" : "35234", "advertiserId" : "ADV-234", "accountId" : "AC-456" } } ] } Errors

Errors will return a JSON object response body with more information.

• 400 - Bad Request

• 403 - Unauthorized

Post - Post Ad Server Acknowledgement

Post Ad Server Acknowledgement.

Request Route

Request Example:

Parameters

Responses

• 204 - No Content

This does not have a body response.

Errors

Errors will return a JSON object response body with more information.

• 400 - Bad Request

• 401 - Unauthorized - Invalid token

• 403 - Forbidden - expired token