Review the information below to learn more about the Auto Tag Light (ATL) API.
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
For all production API calls, use the following Base URL:
https://tags.integralplatform.com
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.
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
Parameter | Type | Required/Optional | Description |
Authorization | string | required | client_id:client_secret
encoded - IAS provides
client_id
and
client_secret . |
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. |
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####"
}
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"
}
See if campaigns are an "APPROVED" or "DECLINED" status.
Example:
GET /linkCampaign/adServer/{adserverAlias}/campaign/{iasCampaignId}/status
Header | Required/Optional | Description |
Authorization | required | string,
bearer {access_token} |
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"
}
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 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.
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 | Required/Optional | Restrictions |
Content-type | Required | String, application/json |
Authorization | Required | String, bearer {access_token} |
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"
}
}
]
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 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 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.
GET /wrapTags/sync/adServer/{adserverAlias}/campaign/{iasCampaignId}
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}'
Parameter | Required/Optional | Restrictions |
Authorization | required | bearer {access_token} |
Content-type | required | application/json |
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 will return a JSON object response body with more information.
400 - Bad Request
401 - Unauthorized
403 - Forbidden
500 and 503 - Internal Error
Create an IAS case with details of your inquiry to receive help from our internal support team.