Skip to content
Verve Retail Media

Get ads

GET
/v1alpha2/ads

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters”
playerid
required
string

Playerid identifies the requesting device/screen. You set it, together with key, on the device’s identifier when you register it.

key
required
string

Key namespaces playerid. Send the same pair the device was registered with.

limit
integer format: int64

Limit bounds the number of ads returned. Online defaults to 1, offline to a server-side cap, 50 today as a safety guard rather than a contract. Ask for what you need and use however many ads come back.

offline
boolean

Offline requests the offline playlist shape: an audience-agnostic set the player stores and replays while it has no connection.

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 Ad elements. Each Ad carries a MediaFile, Impression and TrackingEvents URLs, an AdServingId, a UniversalAdId, and an Extension block of type verve-metadata: JSON with per-ad metadata, defined by the verve-metadata schema. URLs and JSON payloads are wrapped in CDATA. A no-fill is an empty VAST element on HTTP 200.

string format: string
Example
<?xml version="1.0" encoding="UTF-8"?><VAST version="4.2"><Ad><InLine><AdSystem>Verve</AdSystem><Extensions><Extension type="verve-metadata"><![CDATA[{"campaign_id":"cmp_summer","expires_at":"2026-06-05T23:59:59Z","flight_id":"fl_video_01","request_id":"req_9f2","source":"SOURCE_TYPE_AD_SERVER","source_id":"verve-internal"}]]></Extension></Extensions><Impression><![CDATA[https://<host>/v1alpha2/track?asid=b6a1f0c2-7d43-4f1a-9e88-2c5b0d7f3a14&ae=impression&sts=2026-06-05T09:15:00Z]]></Impression><Pricing model="cpm" currency="EUR"><![CDATA[1.5000]]></Pricing><AdServingId>b6a1f0c2-7d43-4f1a-9e88-2c5b0d7f3a14</AdServingId><AdTitle>fl_video_01</AdTitle><Creatives><Creative id="cr_video_01"><Linear><TrackingEvents><Tracking event="creativeView"><![CDATA[https://<host>/v1alpha2/track?asid=b6a1f0c2-7d43-4f1a-9e88-2c5b0d7f3a14&ce=creativeView&sts=2026-06-05T09:15:00Z]]></Tracking><Tracking event="start"><![CDATA[https://<host>/v1alpha2/track?asid=b6a1f0c2-7d43-4f1a-9e88-2c5b0d7f3a14&ce=start&sts=2026-06-05T09:15:00Z]]></Tracking><Tracking event="firstQuartile"><![CDATA[https://<host>/v1alpha2/track?asid=b6a1f0c2-7d43-4f1a-9e88-2c5b0d7f3a14&ce=firstQuartile&sts=2026-06-05T09:15:00Z]]></Tracking><Tracking event="midpoint"><![CDATA[https://<host>/v1alpha2/track?asid=b6a1f0c2-7d43-4f1a-9e88-2c5b0d7f3a14&ce=midpoint&sts=2026-06-05T09:15:00Z]]></Tracking><Tracking event="thirdQuartile"><![CDATA[https://<host>/v1alpha2/track?asid=b6a1f0c2-7d43-4f1a-9e88-2c5b0d7f3a14&ce=thirdQuartile&sts=2026-06-05T09:15:00Z]]></Tracking><Tracking event="complete"><![CDATA[https://<host>/v1alpha2/track?asid=b6a1f0c2-7d43-4f1a-9e88-2c5b0d7f3a14&ce=complete&sts=2026-06-05T09:15:00Z]]></Tracking></TrackingEvents><Duration>00:00:15</Duration><MediaFiles><MediaFile delivery="progressive" type="video/mp4" width="1920" height="1080"><![CDATA[https://cdn.example.com/summer-sale-15s.mp4]]></MediaFile></MediaFiles></Linear><UniversalAdId idRegistry="verve.com">cr_video_01</UniversalAdId></Creative></Creatives><Expires>53099</Expires></InLine></Ad></VAST>