Requesting ads

The Ad API is how a player asks for an ad to show and reports what happened during playback. It is public — no access token and no project header.

The loop

1. Request an ad — GET /v1alpha/adrequest returns a VAST XML document describing the ad to play (or an empty <VAST/> when there’s nothing to show).
2. Play the creative from the VAST response.
3. Report exposure — as playback events occur, fire the tracking URLs carried in the VAST. They point at GET /v1alpha/adexposure.

Optionally, push in-store sensor data with POST /v1alpha/adsignals.

1. Request an ad

GET /v1alpha/adrequest?key=RETAILER_KEY&playerid=PLAYER_ID HTTP/1.1
Host: api.dev.retailmedia.verve.com
Accept: application/xml

Parameter	Required	Description
key	yes	Your retailer key.
playerid	yes	Identifies the player / screen.
seg	no	Audience segment(s); repeat the parameter for multiple.
adv_activation_id	no	Sensor activation id, when one is available.
products	no	Product context for the request.

The response is a VAST <Ad> (or an empty <VAST/>). It carries the creative’s media file plus the impression and tracking URLs to fire.

2. Report exposure

The VAST response stamps the URLs you fire as playback proceeds — fire them verbatim rather than building them yourself. Each one points at GET /v1alpha/adexposure and carries the ad, creative, and which event fired:

GET /v1alpha/adexposure?aid=AD_ID&cid=CREATIVE_ID&ce=<event> HTTP/1.1
Host: api.dev.retailmedia.verve.com

Parameter	Meaning
aid	Ad id.
cid	Creative id.
ae	Ad-level event — impression.
ce	Creative-level event — creative view, start, the quartiles, complete, and more.

A 200 with an empty body means the event was accepted. Replays and retries are safe — the server counts a given event once.

Fire URLs verbatim

Read the impression and tracking URLs straight from the VAST and fire them as the matching playback events happen. Treat them as opaque — don’t parse or reconstruct them.

3. (Optional) Send signals

Push a single in-store signal — vision sensor, smart cart, or e-shelf — with POST /v1alpha/adsignals. The body carries a metadata block (signal, location, and device ids plus a timestamp) and exactly one signal payload.

---

For every parameter, enum value, and response schema, see the Ad API reference.