---
agentTools:
  projectIndex: https://developers.appnext.com/llms.txt
---

# VAST API

Appnext VAST API

**Last updated 23/8/2018**

Video ads have conquered the mobile space, winning the hearts of billions of users across the world. It wasn’t a surprise when apps, both the global giants and the rising stars, embraced the new opportunity. Video ads allow app developers to tell their unique story and give the users a sneak peek of what the app is about delivering a great user experience.

VAST is an XML-based API response format, standard for video ad delivery. It allows publishers to integrate different demand solutions without developing custom integrations for each partner. The basic integration requires video creative, impression reporting, video events reporting, a click-through link. And, voila, you can easily tap into the app video world, securing great user experience and unmatched monetization performance.

[block:api-header]
{
  "title": "Appnext Account & ID"
}
[/block]

**1. Register for an Appnext Account**
You must first create an account with Appnext to be able to use this ad unit’s features.
If you do not have an Appnext account, copy the following URL to the browser: <https://www.appnext.com> and sign up

**2. Get a Unique ID.**
To get started, add a new App via the Appnext Self-Service Platform, then copy the Placement ID, which can be found in your account at:
Apps -> Settings Icon-> Settings & Placements -> Placement ID (make sure to copy the Placement ID for both Android and iOS apps).

[block:parameters]
{
  "data": {
    "0-0": "**Unique ID**\nA unique ID called a “Placement ID” is required for all inbound requests. A Placement ID is a 32- character string generated by Appnext for every registered app."
  },
  "cols": 1,
  "rows": 1
}
[/block]

[block:api-header]
{
  "title": "Getting started with Appnext VAST API"
}
[/block]

## Data returned in Appnext VAST API response

Appnext VAST API returns raw-data of Android or iOS apps, promoted through campaigns by advertisers in the Appnext platform, which specifically target your app placement. Data includes advertiser’s app creative content, current bid, tracking link, ad-serving weight, etc.

## Requesting app data

A “Placement ID”, which is a unique key generated by the Appnext platform, must be added to the VAST API call in order to receive apps data.
Requesting the VAST API with an Android Placement ID will return Android targeted campaigns and requesting it with an iOS Placement ID will return iOS targeted campaigns. Only one OS can be called in a single API call.

## Campaign inventory

Each VAST API request will return data for a single app promotion campaign. By default, the targeted GEO will be determined as the client-side GEO. For example: when requesting the API from a server, located in the US, the API will return a campaign that is targeting US users.

## Campaigns Status

App campaigns constantly change during the day by advertisers. Campaigns are being paused, activated, creative change and bid increase or decrease to compete on your placements via the platform.

Every campaign running has a daily cap (budget). Once a campaign has depleted its daily cap it will be paused until the following day. Campaign that was paused, might not redirect to the store, and will not be eligible for payment.

An JSON file is returned with In case of Capping /Geo Targeting/end of banner inventory/No ads

[block:code]
{
  "codes": [
    {
      "code": "Sample JSON:\n{\nempty:\"\"\n}",
      "language": "json"
    }
  ]
}
[/block]

[block:api-header]
{
  "title": "Measurement and reporting"
}
[/block]

## Impressions count

Counting impressions accurately is important for performance calculations.
Every VAST API response will include an impression URL, for example:

[block:code]
{
  "codes": [
    {
      "code": "<Impression>\nhttps://global.appnext.com/pView.aspx?b=12345&z=12345&c=12345\n</Impression>",
      "language": "xml"
    }
  ]
}
[/block]

## Counting Clicks and installs

Appnext counts a click whenever the <ClickThrough> link, provided by the API for each creative asset / component, is clicked.

[block:callout]
{
  "type": "warning",
  "body": "Do not preload / pre-fetch the urlApp links, as this will generate additional costs to our Advertisers who are using 3rd party tracking solutions for conversion tracking.",
  "title": "Important note:"
}
[/block]

## Postbacks

A Postback (also known as a callback) is a server-to-server call made by Appnext’s server to a publisher’s server with the purpose of notifying him of a conversion (install) made through his app / website.

You may choose to receive up to 3 parameters in each Postback call:

1. Postback parameter – any custom parameter
2. Revenue – the CPI revenue generated for the install
3. Package – the app package
4. IP – IP of the user who installed the app

### Passing a Postback parameter

You can pass Postback data / values for each offer returned by the API. Once a successful install is made, Appnext will call your Postback URL, with the Postback value passed.
In order to pass Postback data / values, make sure to add them to the “\&pbk={value}” parameter to the API call.

Appnext will send Postbacks from these IP addresses: 23.21.212.42, 54.204.84.86 and 184.73.163.42 make sure to white-list all of these addresses.

### Receiving Postbacks

In order to receive Postbacks, you should provide Appnext with a Postback URL. The Postback URL is the endpoint at your server or third-party tracking service, to which we will be sending the Postback.

If you are interested in receiving a Postback, please make sure to set the postback URL in your account, under your app’s settings.

## Sub ID Reporting

Media Partners (such as: ad networks, content networks etc.) are required to pass their publisher’s Sub ID when calling the API.
In order to pass the SubID, add a `“&subid={value}”` to the API call.

## GAID / IDFA

Passing Appnext the Advertising ID / IDFA is mandatory when serving ads in mobile apps.
In order to pass the Advertising ID / IDFA, add a `&did={value}` to the API call.

[block:callout]
{
  "type": "warning",
  "title": "GDPR/Opting out from ads-retargeting",
  "body": "If the user opted out from ads-retargeting, or if the user has not provided consent under the GDPR rules, *do not* pass the GAID/IDFA string. Just send empty value in the `did` parameter"
}
[/block]

## Package name

Passing the app package name is mandatory when serving ads in mobile apps. When using Android apps - please pass the package name. When using iOS apps - please pass iTunes tracking ID (number). The value is passed in the "\&packageId" parameter.

[block:api-header]
{
  "title": "Requesting raw ad data for Android and iOS"
}
[/block]

## VAST API base URL (request):

[block:code]
{
  "codes": [
    {
      "code": "https://global.appnext.com/offerWallApi.aspx?id=PLACEMENT_ID&type=vast&vast_ver=3.0&tid=vast&cv=1&duration=DURATION&did=ADVERTISING_ID&packageId=PACKAGE_NAME&comp_icon=app_icon&comp_title=app_title&comp_desc=app_description&comp_wide_img=app_wide_image&comp_rating=app_rating&comp_downloads=app_number_of_downloads&comp_btn_text=install_button_title",
      "language": "http"
    }
  ]
}
[/block]

[block:api-header]
{
  "title": "API request Parameters:"
}
[/block]

[block:parameters]
{
  "data": {
    "0-0": "Id",
    "0-1": "Placement ID - a 32-character string generated by Appnext for every registered app/mobile-web app that is required for all inbound requests",
    "0-2": "id=0fa643ba-a3e5-4f01-bf49-89354fbd0562\n\nMandatory",
    "0-3": "",
    "1-3": "",
    "3-3": "",
    "1-0": "duration",
    "1-1": "Video length – 15 / 30 seconds long.\nYou can choose between “15” / “30” / “all” (combination of 15 and 30)",
    "1-2": "&duration=all\n\nMandatory",
    "3-0": "did",
    "3-1": "Google Advertising ID / iOS IDFA – a 32-character string",
    "3-2": "&did=aaaaaaaa-bbbb-cccc-1111-222222220000\n\nMandatory",
    "4-3": "",
    "5-3": "",
    "6-3": "",
    "7-3": "",
    "8-3": "",
    "9-3": "",
    "10-3": "",
    "11-3": "",
    "12-3": "",
    "13-3": "",
    "4-0": "subid",
    "4-1": "Required for media partners.\nEnter the publisher id in where the user clicked on the app advertisement.",
    "4-2": "&subid=44332\n\nMandatory for Media Partners",
    "5-0": "pbk",
    "5-1": "Postback Parameters",
    "5-2": "&pbk=YOUR_CUSTOM_PARAMETERS\n\nOptional",
    "6-0": "packageId",
    "6-1": "Unique package ID / device ID of the app showing the ads",
    "6-2": "&packageId=com.chilliapps.freecandy\n\nOptional",
    "7-0": "comp_icon",
    "7-1": "Set the name of the icon component parameter",
    "7-2": "&comp_icon=app_icon\n\nOptional",
    "8-0": "comp_title",
    "8-1": "Set the name of the title component parameter",
    "8-2": "&comp_title=app_title\n\nOptional",
    "9-0": "comp_desc",
    "9-1": "Set the name of the desc component parameter",
    "9-2": "&comp_desc=app_description\n\nOptional",
    "10-0": "comp_wide_img",
    "10-1": "Set the name of the wide img component parameter",
    "10-2": "&comp_wide_img=app_wide_image\n\nOptional",
    "11-0": "comp_rating",
    "11-1": "Set the name of the rating component parameter",
    "11-2": "&comp_rating=app_rating\n\nOptional",
    "12-0": "comp_downloads",
    "12-1": "Set the name of the no. of downloads component parameter",
    "12-2": "&comp_downloads=app_number_of_downloads\n\nOptional",
    "13-0": "comp_btn_text",
    "13-1": "Set the name of the install button text component parameter",
    "13-2": "&comp_btn_text=install_button_title\n\nOptional",
    "h-0": "Parameter",
    "h-3": "Notes",
    "h-2": "Example",
    "h-1": "Description",
    "2-0": "vast_ver",
    "2-1": "The VAST version",
    "2-2": "The default value should be \"3.0\". It is possible to pass \"2.0\" for VAST 2.0 response"
  },
  "cols": 3,
  "rows": 14
}
[/block]

[block:callout]
{
  "type": "warning",
  "body": "\n1. If you are making the call from a server side or a mediation, please contact our support team before making the first call.\n2. Each parameter added to the API string should be added with the “&” symbol. This symbol is used in order to differentiate one parameter from another.\n3. When using multiple categories, make sure to use the following format: \nCategories with 2 words, for example: **Arcade & Action** must be encoded in the following format: **Arcade**%20%26%20**Action** ",
  "title": "Important notes:"
}
[/block]

[block:api-header]
{
  "title": "Response of raw ad data"
}
[/block]

[block:code]
{
  "codes": [
    {
      "code": "<VAST version=\"3.0\">\n<Ad id=\"100880\">\n<InLine>\n<AdSystem version=\"1.0\">Appnext VAST</AdSystem>\n<AdTitle>Knights & Dragons</AdTitle>\n<Impression>\nhttps://admin.appnext.com/pView.aspx?b=100880&z=25526&c=78249\n</Impression>\n<Description>\nKnights & Dragons is a non-stop action role playing game.\n</Description>\n<Pricing>\"cpi,\",\"USD\",\"2.98\"</Pricing>\n<Error>\nhttps://admin.appnext.com/tp12.aspx?ads_type=VAST&tid=VAST&vid=1&pid=0fa643ba-a3e5-4f01-bf49-89354fbd0562&ref=error&bid=100880&cid=78249&callback=ecdca49b-c2c1-45fa-87a3-429da1d9b530\n</Error>\n<Creatives>\n<Creative id=\"100880\">\n<Linear>\n<Duration>00:00:30.000</Duration>\n<VideoClicks>\n<ClickThrough>\n<![CDATA[\nhttps://admin.appnext.com/appLink.aspx?b=100880&e=25526&d=0aaaaaaaa-bbbb-cccc-1111-222222220000&subid=12345&q=test\n]]>\n</ClickThrough>\n</VideoClicks>\n<TrackingEvents>\n<Tracking event=\"start\">\n<![CDATA[\nhttps://admin.appnext.com/tp12.aspx?ads_type=VAST&tid=VAST&vid=1&pid=0fa643ba-a3e5-4f01-bf49-89354fbd0562&ref=play_video&bid=100880&cid=78249&callback=8d801093-a18d-4bfb-a961-eabc686ecda5\n]]>\n</Tracking>\n<Tracking event=\"complete\">\n<![CDATA[\nhttps://admin.appnext.com/tp12.aspx?ads_type=VAST&tid=VAST&vid=1&pid=0fa643ba-a3e5-4f01-bf49-89354fbd0562&ref=video_ended&bid=100880&cid=78249&callback=2c03b9f3-22eb-4d56-baf7-0d4b71283f12\n]]>\n</Tracking>\n</TrackingEvents>\n<MediaFiles>\n<MediaFile delivery=\"progressive\" type=\"video/mp4\" width=\"640\" height=\"360\" bitrate=\"500\" scalable=\"true\" maintainAspectRatio=\"true\">\n<![CDATA[\nhttps://appnext.hs.llnwd.net/banner/video/video-100880-30_o.mp4?rnd=1458234131\n]]>\n</MediaFile>\n<MediaFile delivery=\"progressive\" type=\"video/mp4\" width=\"320\" height=\"180\" bitrate=\"500\" scalable=\"true\" maintainAspectRatio=\"true\">\n<![CDATA[\nhttps://appnext.hs.llnwd.net/banner/video/video-100880-30.mp4?rnd=1458234131\n]]>\n</MediaFile>\n</MediaFiles>\n</Linear>\n</Creative>\n<Creative id=\"100880_companion\" adId=\"100880\">\n<CompanionAds required=\"none\">\n<Companion id=\"app_icon\" width=\"512\" height=\"512\">\n<StaticResource creativeType=\"image/png\">\n<![CDATA[\nhttps://appnext-a.akamaihd.net/banner/r5OkEL3JUHUIZ7j_square.png\n]]>\n</StaticResource>\n<CompanionClickThrough>\n<![CDATA[\nhttps://admin.appnext.com/appLink.aspx?b=100880&e=25526&d=0aaaaaaaa-bbbb-cccc-1111-222222220000&subid=12345&q=test\n]]>\n</CompanionClickThrough>\n</Companion>\n<Companion id=\"app_title\" width=\"0\" height=\"0\">\n<HTMLResource>\n<![CDATA[ Knights & Dragons ]]>\n</HTMLResource>\n<CompanionClickThrough>\nhttps://admin.appnext.com/appLink.aspx?b=100880&e=25526&d=0aaaaaaaa-bbbb-cccc-1111-222222220000&subid=12345&q=test\n</CompanionClickThrough>\n</Companion>\n<Companion id=\"app_description\" width=\"0\" height=\"0\">\n<HTMLResource>\n<![CDATA[\nKnights & Dragons is a non-stop action role playing game.\n]]>\n</HTMLResource>\n<CompanionClickThrough>\nhttps://admin.appnext.com/appLink.aspx?b=100880&e=25526&d=0aaaaaaaa-bbbb-cccc-1111-222222220000&subid=12345&q=test\n</CompanionClickThrough>\n</Companion>\n<Companion id=\"app_wide_image\" width=\"1200\" height=\"628\">\n<StaticResource creativeType=\"image/png\">\n<![CDATA[\nhttps://appnext-a.akamaihd.net/banner/r5OkEL3JUHUIZ7j_rectangular.png\n]]>\n</StaticResource>\n<CompanionClickThrough>\n<![CDATA[\nhttps://admin.appnext.com/appLink.aspx?b=100880&e=25526&d=0aaaaaaaa-bbbb-cccc-1111-222222220000&subid=12345&q=test\n]]>\n</CompanionClickThrough>\n\n</Companion>\n<Companion id=\"app_rating\" width=\"0\" height=\"0\">\n<HTMLResource>\n<![CDATA[ 4.4 ]]>\n</HTMLResource>\n<CompanionClickThrough>\n<![CDATA[\nhttps://admin.appnext.com/appLink.aspx?b=100880&e=25526&d=0aaaaaaaa-bbbb-cccc-1111-222222220000&subid=12345&q=test\n]]>\n</CompanionClickThrough>\n</Companion>\n<Companion id=\"app_number_of_downloads\" width=\"0\" height=\"0\">\n<HTMLResource>\n<![CDATA[ 10000000+ ]]>\n</HTMLResource>\n<CompanionClickThrough>\n<![CDATA[\nhttps://admin.appnext.com/appLink.aspx?b=100880&e=25526&d=0aaaaaaaa-bbbb-cccc-1111-222222220000&subid=12345&q=test\n]]>\n</CompanionClickThrough>\n</Companion>\n<Companion id=\"install_button_title\" width=\"0\" height=\"0\">\n<HTMLResource>Install</HTMLResource>\n<CompanionClickThrough>\n<![CDATA[\nhttps://admin.appnext.com/appLink.aspx?b=100880&e=25526&d=0aaaaaaaa-bbbb-cccc-1111-222222220000&subid=12345&q=test\n]]>\n</CompanionClickThrough>\n</Companion>\n</CompanionAds>\n</Creative>\n</Creatives>\n</InLine>\n</Ad>\n</VAST>",
      "language": "xml"
    }
  ]
}
[/block]

[block:api-header]
{
  "title": "API response Parameters"
}
[/block]

[block:parameters]
{
  "data": {
    "h-0": "Parameter",
    "h-2": "Explanation",
    "h-1": "Description",
    "0-0": "<VAST version=\"3.0\">",
    "0-2": "Supported versions are 3.0 and 2.0",
    "0-1": "VAST version",
    "1-0": "<Ad id=\"100880\">",
    "1-1": "Appnext banner ID",
    "1-2": "Unique ID of the offer",
    "2-0": "<AdSystem version=\"1.0\">",
    "3-0": "<AdTitle>",
    "4-0": "<Impression>",
    "5-0": "<Description>",
    "6-0": "<Pricing>",
    "7-0": "<Error>",
    "8-0": "<Duration>",
    "9-0": "<ClickThrough>",
    "10-0": "<Tracking event=\"start\">",
    "11-0": "<Tracking event=\"complete\">",
    "12-0": "<MediaFile delivery=\"progressive\" type=\"video/mp4\" width=\"640\" height=\"360\" bitrate=\"500\" scalable=\"true\" maintainAspectRatio=\"true\">",
    "13-0": "<MediaFile delivery=\"progressive\" type=\"video/mp4\" width=\"320\" height=\"180\" bitrate=\"500\" scalable=\"true\" maintainAspectRatio=\"true\">",
    "14-0": "<Creative id=\"105116_companion\" adId=\"105116\">",
    "15-0": "<Companion id=\"app_icon\" width=\"512\" height=\"512\">",
    "16-0": "<Companion id=\"app_wide_image\" width=\"1200\" height=\"628\">",
    "17-0": "<Companion id=\"app_title\" width=\"0\" height=\"0\">",
    "18-0": "<Companion id=\"app_description\" width=\"0\" height=\"0\">",
    "19-0": "<Companion id=\"app_rating\" width=\"0\" height=\"0\">",
    "20-0": "<Companion id=\"app_number_of_downloads\" width=\"0\" height=\"0\">",
    "21-0": "<Companion id=\"install_button_title\" width=\"0\" height=\"0\">",
    "22-0": "<CompanionClickThrough>",
    "22-1": "Tracking URL",
    "22-2": "Leads to the app listing on the store",
    "21-1": "Text for the Install button",
    "20-1": "The App’s number of installs on the Appstore / PlayStore",
    "19-1": "The App’s average rating on the Appstore / PlayStore",
    "18-1": "Description of the promoted app",
    "17-1": "Title of the promoted app",
    "16-1": "Wide image, 1200*628 px",
    "16-2": "Cover image of the promoted app",
    "15-1": "Icon image of the promoted app",
    "15-2": "Between 300*300 to 515*515 px",
    "14-1": "Additional creative assets",
    "14-2": "For custom VAST players – highly recommended",
    "13-1": "Low-end video",
    "13-2": "320*180",
    "12-1": "High-end video",
    "12-2": "640*360",
    "11-1": "URL for the video completed event",
    "11-2": "Call when video finished playing",
    "10-1": "URL for the video started event",
    "10-2": "Call when video starts playing",
    "9-1": "Tracking URL",
    "9-2": "Leads to the app listing on the store",
    "8-1": "The duration of the video, in seconds",
    "8-2": "There are 2 slots: 15 and 30 seconds. Video size may be slightly longer or shorter from the given duration",
    "7-1": "Report error URL",
    "6-1": "Cost per install in USD",
    "6-2": "Appnext only works in CPI model",
    "5-1": "Description of the promoted app",
    "5-2": "Up to 90 chars",
    "4-1": "Impression URL",
    "3-1": "Title of the promoted app",
    "3-2": "Up to 25 chars",
    "2-1": "Appnext VAST version"
  },
  "cols": 3,
  "rows": 23
}
[/block]

[block:api-header]
{
  "title": "App Categories"
}
[/block]

[block:parameters]
{
  "data": {
    "0-0": "**Android:**\n1. Action\n2. Adventure\n3. Arcade\n4. Arcade & Action\n5. Board\n6. Books & Reference\n7. Brain & Puzzle\n8. Business\n9. Card\n10. Cards & Casino\n11. Casino\n12. Casual\n13. Comics\n14. Communications\n15. Education\n16. Educational\n17. Entertainment\n18. Family\n19. Finance\n20. Health & Fitness\n21. Libraries & Demo\n22. Lifestyle\n23. Live Wallpaper\n24. Media & Video\n25. Medical\n26. Music\n27. Music & Audio\n28. News & Magazines\n29. Personalization",
    "0-1": "30. Photography\n31. Productivity\n32. Puzzle\n33. Racing\n35. Shopping\n36. Simulation\n37. Social\n38. Sports\n39. Sports Games\n40. Strategy\n41. Tools\n42. Travel & Local\n43. Trivia\n44. Weather\n45. Word\n\n**iOS:**\n1. Action\n2. Adventure\n3. Arcade\n4. Board\n5. Books\n6. Business\n7. Card\n8. Casino\n9. Catalogs\n10. Dice\t11. Education\n12. Educational\n13. Entertainment\n14. Family",
    "0-2": "15. Finance\n16. Food & Drink\n17. Graphics & Design\n18. Health & Fitness\n19. Kids\n20. Lifestyle\n21. Medical\n22. Music\n23. Navigation\n24. News\n25. Photo & Video\n26. Productivity\n27. Puzzle\n28. Racing\n29. Reference\n30. Role Playing\n31. Simulation\n32. Social Networking\n33. Sports\n34. Strategy\n35. Travel\n36. Trivia\n37. Utilities\n38. Weather"
  },
  "cols": 3,
  "rows": 1
}
[/block]

Make sure to encode (%20) categories with more than 1 word, example: **Travel**%20%26%20**Local**