Skip to content
Verve Retail Media

Get ads

GET
/v1alpha2/ads

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
playerid
string

Playerid identifies the requesting device/screen. Proto field name is the GET query param (?playerid=…)

key
string

Key is the optional retailer/context key; when present it is concatenated with playerid (key + playerid) to form the context lookup id.

limit
integer format: int64

Limit bounds the number of ads returned. Slice 1 supports limit=1.

offline
boolean

Offline requests the offline playlist shape. Not available in slice 1.

dvactid
string

Dvactid is the opaque Advertima activation id, sealed into the decision.

source
Array<string>
Allowed values: SOURCE_TYPE_UNSPECIFIED SOURCE_TYPE_AD_SERVER SOURCE_TYPE_SSP SOURCE_TYPE_CMS

Source filters the response to the given supply types, post-selection. Multiple values are OR’d. Omitted = all sources eligible.

seg
string

Seg: live demographics as ;-separated IAB Taxonomy 1.1 profiles, segId[.segId…][:count] (’.’ = AND, ‘:count’ = shoppers, default 1). Requires a demographic sensor; online only (400 if offline). Example: seg=49.5:3;50:2 (3 female aged 25-29; 2 male).

products
string

Products: the shopper’s basket as ;-separated sku[:qty] entries (qty default 1, parsed from the right). Requires SENSOR_BASKET; online only (400 if offline). Example: products=sku-123:2;sku-456 (2x sku-123, 1x sku-456).

retail_grocery_zone
string
default: VENUE_RETAIL_GROCERY_UNSPECIFIED
Allowed values: VENUE_RETAIL_GROCERY_UNSPECIFIED VENUE_RETAIL_GROCERY_ENTRANCE VENUE_RETAIL_GROCERY_CHECK_OUT VENUE_RETAIL_GROCERY_AISLES VENUE_RETAIL_GROCERY_EXTERIOR

Retail_grocery_zone: the player’s zone within a grocery store, e.g. VENUE_RETAIL_GROCERY_CHECK_OUT. Mutually exclusive with retail_mall_zone.

retail_mall_zone
string
default: VENUE_RETAIL_MALLS_UNSPECIFIED
Allowed values: VENUE_RETAIL_MALLS_UNSPECIFIED VENUE_RETAIL_MALLS_CONCOURSE VENUE_RETAIL_MALLS_FOOD_COURT VENUE_RETAIL_MALLS_SPECTACULAR

Retail_mall_zone: the player’s zone within a mall, e.g. VENUE_RETAIL_MALLS_FOOD_COURT. Mutually exclusive with retail_grocery_zone.

  • VENUE_RETAIL_MALLS_CONCOURSE: Large open area including hallways and escalators.
  • VENUE_RETAIL_MALLS_FOOD_COURT: Common area with multiple food vendors and tables.
  • VENUE_RETAIL_MALLS_SPECTACULAR: Large impactful screens at prime locations.
aisle
string
default: AISLE_UNSPECIFIED
Allowed values: AISLE_UNSPECIFIED AISLE_ALCOHOL AISLE_BABY AISLE_BAKERY AISLE_BAKING AISLE_BEVERAGE AISLE_BREAD AISLE_BREAKFAST AISLE_BUTCHER AISLE_BUTTER AISLE_CANNED AISLE_CHEESE AISLE_CONDIMENTS AISLE_DAIRY AISLE_DELI AISLE_FROZEN AISLE_GRAINS AISLE_HOUSEHOLD_CLEANING AISLE_MEAT AISLE_PASTA AISLE_PERSONAL_CARE AISLE_PET AISLE_PRODUCE AISLE_SEAFOOD AISLE_SNACK

Aisle: the grocery product aisle the player is at, implying the grocery AISLES zone. Accepted alone or with retail_grocery_zone = AISLES; any other zone is a 400. Single-valued (a moving player is at one aisle, unlike a fixed screen). Requires SENSOR_LOCATION; online only (400 if offline). Example: aisle=AISLE_DAIRY.

Responses

Section titled “Responses”

200

Section titled “200”

VAST 4.2 XML document. See the Requesting ads guide for full response examples covering video, image, and HTML5 creatives.

Media typeapplication/xml
VAST

A VAST 4.2 XML document with one or more elements. Each carries a , and URLs, an , and a block with per-ad metadata (expires_at, source, source_id, request_id).

string format: string
Example
<VAST version="4.2">
  <Ad>
    <InLine>
      <AdSystem>Verve</AdSystem>
      <AdServingId>srv_a1</AdServingId>
      <AdTitle>Summer Sale Video</AdTitle>
      <Impression>https://&lt;host&gt;/v1alpha2/track?asid=srv_a1&ae=impression&sts=2026-06-05T09:15:00Z</Impression>
      <Pricing model="cpm" currency="EUR">1.5000</Pricing>
      <Creatives>
        <Creative id="cr_video_01">
          <Linear>
            <Duration>00:00:15</Duration>
            <MediaFiles>
              <MediaFile delivery="progressive" type="video/mp4" width="1920" height="1080">https://cdn/video-ad.mp4</MediaFile>
            </MediaFiles>
            <TrackingEvents>
              <Tracking event="creativeView">https://&lt;host&gt;/v1alpha2/track?asid=srv_a1&ce=creativeView&sts=...</Tracking>
              <Tracking event="start">https://&lt;host&gt;/v1alpha2/track?asid=srv_a1&ce=start&sts=...</Tracking>
              <Tracking event="firstQuartile">https://&lt;host&gt;/v1alpha2/track?asid=srv_a1&ce=firstQuartile&sts=...</Tracking>
              <Tracking event="midpoint">https://&lt;host&gt;/v1alpha2/track?asid=srv_a1&ce=midpoint&sts=...</Tracking>
              <Tracking event="thirdQuartile">https://&lt;host&gt;/v1alpha2/track?asid=srv_a1&ce=thirdQuartile&sts=...</Tracking>
              <Tracking event="complete">https://&lt;host&gt;/v1alpha2/track?asid=srv_a1&ce=complete&sts=...</Tracking>
            </TrackingEvents>
          </Linear>
        </Creative>
      </Creatives>
      <Extensions>
        <Extension type="verve-metadata">{"flight_id":"fl_video_01","campaign_id":"cmp_summer","source":"SOURCE_TYPE_AD_SERVER","source_id":"ad_server","request_id":"req_9f2","expires_at":"2026-06-05T23:59:59Z"}</Extension>
      </Extensions>
    </InLine>
  </Ad>
</VAST>