Auto Tag Light API

Review the information below to learn more about the Auto Tag Light (ATL) API.

Introduction & Base URL

The Auto Tag Light API (ATL) enables mutual ad server and IAS clients to:

  • Synchronously get wrapped tags

  • Get tags with macros

  • Use UVP with quartiles

  • Use client to server tag wrapping

Further, ATL automatically wraps these types of tags:

  • VAST

  • VPaid Monitoring

  • VPaid Blocking

  • CTV

Base URL

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

https://tags.integralplatform.com

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.

The Authorization token remains valid for 8 hours.

Example cURL template:

curl --user {client_id}:{client_secret} -H 'Content-Type: application/x-www-form-urlencoded' --data 'username={userName}&password={password}&grant_type=password' https://api.integralplatform.com/uaa/oauth/token

Headers

Parameter

Type

Required/Optional

Description

Authorization

string

required

client_id:client_secret

encoded - IAS provides

client_id

and

client_secret

.

Request Body


Parameter

Type

Required/Optional

Description

grant_type

string

required

The grant_type parameter must be set to

client_credentials

.

username

string

required

Identifier for the ad server. IAS provides this.

password

string

required

Password ad server generates through IAS system.

Authorization Response

  • 200 - Success

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

{
"access_token": "xxx",
"token_type": "bearer",
"expires_in": 21599,
"scope": "nemo",
"jti": "#xxxx###-###x-#x##-x#x#-xxx#x#x####"
}

Errors

  • 403 - Forbidden

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

403 - Forbidden Response Example:

{
"code": "xxx",
"summary": "The OAuth 2.0 server found an error with an invalid, forbidden, a 'No Token' or an expired token. If
the token is expired, you need to acquire a new token.",
"doc": "https://ias-documentation-url?code=xxx"
}

Get Campaign Status

See if campaigns are an "APPROVED" or "DECLINED" status.

Route

Example:

GET /linkCampaign/adServer/{adserverAlias}/campaign/{iasCampaignId}/status

Headers & Schema

Header

Required/Optional

Description

Authorization

required

string,

bearer {access_token}

Response

Parameter

Type

Required/Optional

Description

id

Numeric

required

IAS Campaign ID

name

String

required

Campaign Name

status

enum

optional

Possible values: "APPROVED", "DECLINED"

  • 200 - Success

200 - Success Response Example:

{
"id" : 1234,
"name" : "Some campaign name",
"status" : "APPROVED"
}

Errors

  • 400 - Bad request - Internal error on team linking

  • 401 - Unauthorized - Issues validating the caller

  • 403 - Forbidden - The token is correct but the user doesn't have permissions to access the endpoint.

  • 500 & 503 - Internal Error - The service is currently unavailable due to an internal error.

Send Tags for Wrapping

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

Route

POST /wrapTags/sync/adServer/{adserverAlias}/campaign/{iasCampaignId}

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

Example cURL Template:

curl -X POST -H "Authorization: bearer {access_token}" -H "Content-Type: application/json" https://tags.integralplatform.com/wrapTags/sync/adServer/{adserverAlias}/campaign/{iasCampaignId} --data '{JSON BODY}'

Header Schema

Header

Required/Optional

Restrictions

Content-type

Required

String, application/json

Authorization

Required

String, bearer {access_token}

Request Body Examples & Schema

Parameter

Type

Required?

Possible Values

Description

id

string

required


Placement ID

name

string

optional



siteName

string

required


Name of the publisher, or website on which the ad is to be served. If the value doesn’t match a publisher in the IAS system, the API creates a new, unmapped publisher, and status will be "pending" until publisher is mapped to media partner.

format

string

required

"DISPLAY", "VIDEO", "TRACKING", "VIDEOPIXEL", "VIDEO_UVT_NON_VPAID"

Placement media type.

size

string

If format is display, then required. If format is video, then optional. If format is tracking, then optional.


Ad size. Array of Strings.

startDate

{YYYYMMDD}

optional


Placement Start date for when the placement is booked to start serving.

solution

string

required

MONITORING, BLOCKING


displayTags.javascript.url

string

optional


If the format is display, there should be at least 1 URL for JavaScript, image, or iFrame. If you add this parameter, it must be a URL with correct URI syntax.

displayTags.image.url

string

optional


If the format is display, there should be at least 1 URL for JavaScript, image, or iFrame. If you add this parameter, it must be a URL with correct URI syntax.

displayTags.iframe.url

string

optional


If the format is display, there should be at least 1 URL for JavaScript, image, or iFrame. If you add this parameter, it must be a URL with correct URI syntax.

videoTag.url

string

optional


If the format is one of video type, then the video URL should be present. If you add this parameter, it must be a URL with correct URI syntax.

Request Examples:

Request Example for Display Tag:

[
{
"id": "adserverPlacementID",
"name": "placementName",
"siteName": "siteName",
"format": "DISPLAY",
"size": "200x200",
"startDate": "20210501",
"solution" : "BLOCKING",
"displayTags": {
"javascript": {
"url" : "https://domain.com/path/123/script.bs?params"
},
"image": {
"url" : "https://domain.com/path/456/script.bs?params"
}
}
}
]

Request Example for a Video Tag:

[
{
"id": "adserverPlacementID",
"name": "placementName",
"siteName": "siteName",
"startDate": "20210501",
"format": "VIDEO_PIXEL",
"solution" : "BLOCKING",
"videoTag": {
"url" : "https://someDomain.com/path?params"
}
}
]

Response Body Examples & Schema

  • 200 - Success

Response Bodies include the same parameters as Request Bodies, and these additional parameters:

Parameter

Type

Required?

Possible Values

Description

status

string

required

WRAPPED or FAILED


blockingAllowed

boolean

required


Indicative if blocking solution is supported by the media partner in case it needs to be changed from monitoring to blocking.

reason

string

optional


Descriptive message with the reason why the wrapping failed. This is for development purposes.

reasonCode

string

optional

"UNMAPPED_PUBLISHER", "MEDIA_PARTNER_NOT_IN_CAMPAIGN", "SOW_NOT_SIGNED", "BLOCKING_NOT_SUPPORTED", "FORMAT_NOT_SUPPORTED"


displayTags.javascript.adsafeurl

string

optional


Display URL wrapped.

displayTags.javascript.pubEntityIds

Array of Strings

optional


Set containing the pub entity IDs related with the adsafe URLs

displayTags.image.adsafeurl

string

required

MONITORING, BLOCKING

Display URL wrapped.

displayTags.image.pubEntityIds

Array of Strings

optional


Set containing the pub entity ids related with the adsafe URLs

displayTags.iframe.adsafeurl

string

optional


Display URL wrapped.

displayTags.iframe.pubEntityIds

Array of Strings

optional


Set containing the pub entity ids related with the adsafe URLs

videoTag.adsafeurl

string

optional


Video URL wrapped.

200 - Success Response Example for Display as Blocking:

[
{
"id": "adserverPlacementID",
"name": "placementName",
"siteName": "siteName",
"format": "DISPLAY",
"size": "200x200",
"startDate": "20210501",
"solution" : "BLOCKING",
"displayTags": {
"javascript": {
"url" : "https://domain.com/path/123/script.bs?params",
"adsafeUrl": "https://fw.adsafeprotected.com/rjss/domain.com/{advEntity}/{pubEntityA}/path/script.bs?params&iasMacros",
"pubEntityIds": [
"{pubEntityA}"
]
},
"image": {
"url" : "https://domain.com/path/456/script.bs?params",
"adsafeUrl": "https://fw.adsafeprotected.com/rfw/domain.com/{advEntity}/{pubEntityB}/path/script.bs?params&iasMacros",
"pubEntityIds": [
"{pubEntityB}"
]
}
},
"blockingAllowed": true,
"status": "WRAPPED"
}
]

200 - Success Response Example for Display as Monitoring:

[
{
"id": "adserverPlacementID",
"name": "placementName",
"siteName": "siteName",
"format": "DISPLAY",
"size": "200x200",
"startDate": "20190501",
"solution" : "MONITORING",
"displayTags": {
"javascript": {
"url" : "https://domain.com/path/script.bs?params",
"adsafeUrl": "<SCRIPT TYPE=\"application/javascript\" SRC=\"https://pixel.adsafeprotected.com/rjss/st/{advEntityId}/{pubEntityIdA}/skeleton.js\"></SCRIPT> <NOSCRIPT><IMG SRC=\"https://pixel.adsafeprotected.com/rfw/st/{advEntityId}/{pubEntityIdB}/skeleton.gif?gdpr=${GDPR}&gdpr_consent=${GDPR_CONSENT_278}&gdpr_pd=${GDPR_PD}\" BORDER=0 WIDTH=1 HEIGHT=1 ALT=\"\"></NOSCRIPT>",
"pubEntityIds": [
"{pubEntityA}",
"{pubEntityB}"
]
},
"image": {
"url" : "https://domain.com/path/script.bs?params",
"adsafeUrl": "<SCRIPT TYPE=\"application/javascript\" SRC=\"https://pixel.adsafeprotected.com/rjss/st/{advEntityId}/{pubEntityIdA}/skeleton.js\"></SCRIPT> <NOSCRIPT><IMG SRC=\"https://pixel.adsafeprotected.com/rfw/st/{advEntityId}/{pubEntityIdB}/skeleton.gif?gdpr=${GDPR}&gdpr_consent=${GDPR_CONSENT_278}&gdpr_pd=${GDPR_PD}\" BORDER=0 WIDTH=1 HEIGHT=1 ALT=\"\"></NOSCRIPT>",
"pubEntityIds": [
"{pubEntityA}",
"{pubEntityB}"
]
},
"iframe" : {
"url" : "https://domain.com/path/script.bs?params",
"adsafeUrl": "<SCRIPT TYPE=\"application/javascript\" SRC=\"https://pixel.adsafeprotected.com/rjss/st/{advEntityId}/{pubEntityIdA}/skeleton.js\"></SCRIPT> <NOSCRIPT><IMG SRC=\"https://pixel.adsafeprotected.com/rfw/st/{advEntityId}/{pubEntityIdB}/skeleton.gif?gdpr=${GDPR}&gdpr_consent=${GDPR_CONSENT_278}&gdpr_pd=${GDPR_PD}\" BORDER=0 WIDTH=1 HEIGHT=1 ALT=\"\"></NOSCRIPT>",
"pubEntityIds": [
"{pubEntityA}",
"{pubEntityB}"
]
}
},
"blockingAllowed": true,
"status": "WRAPPED"
}
]

200 - Success Response Example for a Unified Video Tag:

[
{
"id": "adserverPlacementID",
"name": "placementName",
"siteName": "siteName",
"startDate": "20210501",
"format": "VIDEO_PIXEL",
"solution" : "BLOCKING",
"videoTag": {
"url" : "https://someDomain.com/path?params",
"adsafeurl": "https://unified.adsafeprotected.com/v2/{advEntityId}/{pubEntityId}?mon={auxPubEntityId}&omidPartner=[OMIDPARTNER]&apiframeworks=[APIFRAMEWORKS]&bundleId=[BUNDLEID]&blockedAdTracking=${DC_BLOCKED_AD}&originalVast=https://someDomain.com/path?params"
},
"blockingAllowed": true,
"status": "WRAPPED"
}
]

Errors

Errors will return a JSON object response body with more information

  • 400 - Bad Request Request has syntax issues

  • 401 - Unauthorized Issues validating the caller

  • 403 - Forbidden The token is correct but the user doesn't permissions to access the endpoint.

  • 500 and 503 - Internal Error The service is currently unavailable due to an internal error.

Get Wrapped Tags

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, after 30 seconds, tags are still not ready, we recommend calling this endpoint no more than once every 5 minutes to check if your tags are ready.

Route

GET /wrapTags/sync/adServer/{adserverAlias}/campaign/{iasCampaignId}

Example cURL Template:

curl -X GET -H "Authorization: bearer {access_token}" -H "Content-Type: application/json" https://tags.integralplatform.com/wrapTags/sync/adServer/{adserverAlias}/campaign/{iasCampaignId} --data '{JSON BODY}'

Headers

Parameter

Required/Optional

Restrictions

Authorization

required

bearer {access_token}

Content-type

required

application/json

Responses

  • 200 - Success

The example below shows what a successful response looks like.

200 - Success Wrapped Response Example:

[
{
"blockingAllowed": true,
"id": "adserverPlacementID1",
"name": "adserverPlacement1",
"siteName": "siteName",
"format": "DISPLAY",
"size": "200x200",
"solution": "BLOCKING",
"displayTags": {
"javascript": {
"adsafeurl": "https://fw.adsafeprotected.com/rjss/domain.com/123456/12345678/path/script.bs?params",
"pubEntityIds": [ "12345678" ]
},
"image": {
"adsafeurl": "https://fw.adsafeprotected.com/rfw/domain.com/123456/12345678/path/script.bs?params",
"pubEntityIds": [ "12345678" ]
},
"iframe": {
"adsafeurl": "https://fw.adsafeprotected.com/rjsi/domain.com/123456/12345678/path/script.bs?params",
"pubEntityIds": [ "12345678" ]
}
}
},
{
"blockingAllowed": true,
"id": "adserverPlacementID2",
"name": "adserverPlacement2",
"siteName": "siteName",
"format": "DISPLAY",
"size": "200x200",
"solution": "MONITORING",
"displayTags": {
"javascript": {
"adsafeurl": "<SCRIPT TYPE=\"application/javascript\" SRC=\"https://pixel.adsafeprotected.com/rjss/st/123456/12345678/skeleton.js\"></SCRIPT> <NOSCRIPT><IMG SRC=\"https://pixel.adsafeprotected.com/rfw/st/123456/12345679/skeleton.gif?gdpr=${GDPR}&gdpr_consent=${GDPR_CONSENT_278}&gdpr_pd=${GDPR_PD}\" BORDER=0 WIDTH=1 HEIGHT=1 ALT=\"\"></NOSCRIPT>",
"pubEntityIds": [
"12345678",
"12345679"
]
},
"image": {
"adsafeurl": "<SCRIPT TYPE=\"application/javascript\" SRC=\"https://pixel.adsafeprotected.com/rjss/st/123456/12345678/skeleton.js\"></SCRIPT> <NOSCRIPT><IMG SRC=\"https://pixel.adsafeprotected.com/rfw/st/123456/12345679/skeleton.gif?gdpr=${GDPR}&gdpr_consent=${GDPR_CONSENT_278}&gdpr_pd=${GDPR_PD}\" BORDER=0 WIDTH=1 HEIGHT=1 ALT=\"\"></NOSCRIPT>",
"pubEntityIds": [
"12345678",
"12345679"
]
},
"iframe": {
"adsafeurl": "<SCRIPT TYPE=\"application/javascript\" SRC=\"https://pixel.adsafeprotected.com/rjss/st/123456/12345678/skeleton.js\"></SCRIPT> <NOSCRIPT><IMG SRC=\"https://pixel.adsafeprotected.com/rfw/st/123456/12345679/skeleton.gif?gdpr=${GDPR}&gdpr_consent=${GDPR_CONSENT_278}&gdpr_pd=${GDPR_PD}\" BORDER=0 WIDTH=1 HEIGHT=1 ALT=\"\"></NOSCRIPT>",
"pubEntityIds": [
"12345678",
"12345679"
]
}
}
},
{
"blockingAllowed": true,
"id": "adserverPlacementID3",
"name": "adserverPlacement3",
"siteName": "siteName",
"format": "VIDEO_VPAID",
"size": "640x360",
"solution": "BLOCKING",
"videoTag": {
"adsafeurl": "http://fw.adsafeprotected.com/vast/rfw/st/123456/12345678/skeleton.js?originalVast=http://innovid.ias.sdk.integration.placeholder.com/skeleton.js?fake_xml.xml"
}
}
]

Errors

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

  • 400 - Bad Request

  • 401 - Unauthorized

  • 403 - Forbidden

  • 500 and 503 - Internal Error


Was this article helpful?

Need further help?

Create an IAS case with details of your inquiry to receive help from our internal support team.